跳到內容

將 Astro 網站部署到 GitHub Pages

你可以使用 GitHub Pages 透過 GitHub Actions 直接從 GitHub.com 的儲存庫架設靜態、預先算繪的 Astro 網站。

如何部署

Section titled “如何部署”

Astro 維護了官方的 Astro GitHub Action 用於部署專案至 GitHub Pages，只需要極少的設定，這是官方推薦的 GitHub Pages 部署方式。

跟著下面的指示，使用 GitHub Action 將你的 Astro 網站部署到 GitHub Pages。這會從儲存庫建立位於 GitHub URL（例如 https://<username>.github.io/<my-repo>）的網站。部署完成後，你可以選擇設定自訂網域，將 GitHub Pages 網站部署到你偏好的網域（例如 https://example.com）。

  1. 在專案內新增 .github/workflows/deploy.yml 檔案，並貼上下面的 YAML。

    deploy.yml
    name: Deploy to GitHub Pages
    

    on:
      # 在每次推送到 `main` 分支時觸發 workflow
      # 如果你想要在別的分支上觸發，請將 `main` 替換成你想要的分支名稱
      push:
        branches: [ main ]
      # 允許你在 GitHub 上的 Actions 分頁中手動觸發這個 workflow
      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@v6
          - name: Install, build, and upload your site
            uses: withastro/action@v6
            # with:
              # path: . # 儲存庫中 Astro 專案的根位置。（可選）
              # node-version: 24 # 用於建置網站的特定 Node.js 版本，預設為 24。（可選）
              # package-manager: pnpm@latest # 應該使用哪個 Node.js 套件管理器來安裝相依套件和建置網站，會根據儲存庫中的 lockfile 自動檢測。（可選）
              # build-cmd: pnpm run build # 用來建置網站的指令。預設會執行套件的建置腳本／任務。（可選）
            # env:
              # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # 變數的值請用單引號括住（可選）
    

      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@v5

    你可以透過可選的輸入設定 Astro action。若要提供這些參數，請取消註解 with: 這一行，以及你想要使用的輸入。

    如果網站需要任何公開的環境變數，請取消註解 env: 這一行，並在這裡加入。（要加入私密的環境變數，請參見 GitHub 關於設定秘密的文件。）

  2. 在 Astro 設定檔，將 site (EN) 設為你要部署網站的 GitHub URL。

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://astronaut.github.io',
    })

    site 的值必須是下面其中一個：

    • 根據你的使用者名稱產生的下列 URL：https://<username>.github.io
    • 為 GitHub 組織私人頁面 自動產生的隨機 URL：https://<random-string>.pages.github.io/

  3. 在 astro.config.mjs，為 base (EN) 設定一個值（通常需要）。

    GitHub Pages 發佈網站的網址取決於你的使用者名稱與儲存庫名稱（例如 https://<username>.github.io/<my-repo>/）。請為 base 設定一個值來為網站指定儲存庫。這是為了讓 Astro 了解網站的根目錄是 /my-repo 而不是預設的 /。如果你的儲存庫名稱符合特殊的 <username>.github.io 格式（例如 https://github.com/username/username.github.io/），則可以跳過這一步。

    將 base 設定成斜線開頭再加上儲存庫名稱（例如 /my-repo）：

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://astronaut.github.io',
      base: '/my-repo',
    })

  4. 在 GitHub 網站上，請切換到儲存庫中的 Settings 分頁，並找到設定的 Pages 部分。

  5. 選擇 GitHub Actions 作為網站的 Source。

當你推送變更到 Astro 專案的儲存庫，GitHub Action 會自動將它們部署到你的 GitHub URL 上。

更改 GitHub URL 至自訂網域

Section titled “更改 GitHub URL 至自訂網域”

一旦你跟著前面的指示將 Astro 專案部署到 GitHub pages 的 GitHub URL 後，你就可以設定自訂網域。這代表使用者可以透過自訂網域 https://example.com 來造訪你的網站，而不是 https://<username>.github.io。

  1. 在你的網域供應商設定 DNS。

  2. 將 ./public/CNAME 記錄新增至專案中。

    在 public/ 資料夾建立以下檔案，裡面包含一行指定自訂網域的文字：

    public/CNAME
    sub.example.com

    這會將你的網站部署到你的自訂網域，而不是 user.github.io。

  3. 在 Astro 設定內，將 site 的值更新為自訂域名。不要有 base 的設定值，如果存在請去掉：

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://example.com',
      base: '/my-repo'
    })

  4. 如果需要，請更新所有頁面內部連結以去除 base 前綴：

    <a href="/my-repo/about">關於</a>

範例

Section titled “範例”

更多部署指南

貢獻 社群 贊助