將 Astro 網站部署到 GitHub Pages

你可以透過 GitHub Pages 直接從 GitHub 的儲存庫中部署你的 Astro 網站。

如何部署

你可以透過 GitHub Actions 自動將 Astro 網站搭建並部署到 GitHub Pages 上。正因如此，網站的原始碼必須要放在 Github 上。

Astro 官方提供的 withastro/action 可以只使用極少的設定就部署好專案。跟著下方的說明，即可在 GitHub pages 上部署你的 Astro 網站。詳細資訊請詳閱套件的 README。

在 Github Pages 設定 Astro

部署至 `github.io` 網址

請在 astro.config.mjs 的設定檔中設定 site (EN) 與 base (EN) 兩個選項。

import { defineConfig } from 'astro/config'

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

`site`

請確保 site 值為以下的其中之一：

以你的使用者名稱產生的網址，如：https://<username>.github.io
為 GitHub 組織的不公開頁面所產生的亂數網址，如：https://<random-string>.pages.github.io/

`base`

你可能需要設定 base，這樣 Astro 才會將儲存庫名稱（例如 /my-repo）視為網站的根目錄。

base 的內容應該是你的儲存庫名稱，並以正斜線開頭，例如 /my-blog。這樣做是為了讓 Astro 理解你的網站根目錄是 /my-repo，而不是預設的 /。

當設定了這個值後，你所有的內部頁面連結都必須以所設定的 base 值作為前綴：

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

你可以在設定 base 值 (EN)中找到更多相關資訊。

使用自定義網域名稱的 GitHub Pages

你可以透過在專案建立 ./public/CNAME 檔案來設定自訂網域名稱：

sub.mydomain.com

這會將網站部署在所指定的自訂網域名稱下，而非 <YOUR_USERNAME>.github.io。不要忘記為你的域名提供商設定 GitHub Pages。

為了設定 Astro 在 GitHub Pages 上使用你的自訂網域，請將網域名稱設定成 site 的值，並請不要設定 base：

import { defineConfig } from 'astro/config'

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

設定 GitHub Action

在專案的 .github/workflows/ 資料夾中建立名為 deploy.yml 的新檔案，並將以下 YAML 設定貼進其中。

name: Deploy to GitHub Pages

on:
  # 在每次推送到 `main` 分支時觸發部署
  # 如果你想要在其他分支上觸發部署，請將 `main` 替換成你想要的分支名稱
  push:
    branches: [ main ]
  # 允許你在 GitHub 上的 Actions 分頁中手動觸發此部署
  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@v3
        # with:
          # path: . # 儲存庫中 Astro 專案的根位置。（可選）
          # node-version: 20 # 用於建置網站的特定 Node.js 版本，預設為 20。（可選）
          # package-manager: pnpm@latest # 應該使用哪個 Node.js 套件管理器來安裝相依套件和建置網站，會根據儲存庫中的 lockfile 自動檢測。（可選）

  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