Astro 部署到 GitHub Pages 示範

在 GitHub 上建立專案， 並且使用指令建立一個 astro 的空專案：

    
npm create astro@latest
    

在專案資料夾下建立 .github/workflows/deploy.yml 檔案：

    
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      - name: Install, build, and upload your site
        uses: withastro/action@v2

(optional)

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
    

上面的 yml 檔案是 GitHub Actions 的設定檔，主要用途是當 commit 推送至 main 分支時會自動建立並部署到 GitHub Pages 中，還有打包和部署的流程。
註：如果預設分支是 master 的記得要替換為 [ master ]

在 astro.config.mjs 檔案中加入以下設定：

    
import { defineConfig } from 'astro/config';

export default defineConfig({
    site: 'https://ruyut.github.io', // 將 ruyut 替換為自己的 github 使用者名稱
    base: 'astro-github-page-test', // 將 astro-github-page-test 替換為專案名稱
});

    

以筆者 GitHub 使用者名稱: ruyut 專案名稱 astro-github-page-test 為例， GitHub Page 網址如下：

    
https://ruyut.github.io/astro-github-page-test/
    

這是因為 GitHub Page 不是給我們一個網域，而是有加上儲存庫名稱的目錄，所以才要設定 base。 並且網站內的
站內連結都需要加上儲存庫名稱
例如：

    
/astro-github-page-test/about
    

不然在切換連結時本該指向的 https://ruyut.github.io/astro-github-page-test/about 的連結很可能會指向 https://ruyut.github.io/about 導致找不到頁面 404

在推送到 GitHub 前要先到專案的 Settings > Pages ，將 Build and deployment 的 Source 選擇 GitHub Actions

不然執行時會出現打包成功但部署失敗，顯示找不到 Pages：

    
 Error: Creating Pages deployment failed
Error: HttpError: Not Found
    at /home/runner/work/_actions/actions/deploy-pages/v4/node_modules/@octokit/request/dist-node/index.js:124:1
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at createPagesDeployment (/home/runner/work/_actions/actions/deploy-pages/v4/src/internal/api-client.js:125:1)
    at Deployment.create (/home/runner/work/_actions/actions/deploy-pages/v4/src/internal/deployment.js:74:1)
    at main (/home/runner/work/_actions/actions/deploy-pages/v4/src/index.js:30:1)
Error: Error: Failed to create deployment (status: 404) with build version 0bc74498605a6abf64c2b72ae96a8d088a78d048. Request ID 4CD1:17752F:6D99AB:B8904C:66268944 Ensure GitHub Pages has been enabled: https://github.com/ruyut/astro-github-page-test/settings/pages
    

將 astro 推送至 GitHub 儲存庫後會自動開始執行 GitHub Action
等待打包和部署完畢：

點選 Action 頁籤 > Deployments 就會看到部署的頁面網址：

點選該連結就會看到部屬好的網站了！

參考資料：
Astro.Docs - Deploy your Astro Site to GitHub Pages