Skip to content

i18n(zh-tw): update guides/deploy/github.mdx #13996

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vrabe wants to merge 2 commits into
base: main
Choose a base branch
from
Open

i18n(zh-tw): update guides/deploy/github.mdx #13996

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c453f71
i18n(zh-tw): update `guides/deploy/github.mdx`
vrabe Jun 5, 2026
fa4b741
fix a link
vrabe Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 98 additions & 104 deletions src/content/docs/zh-tw/guides/deploy/github.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,95 +10,26 @@ i18nReady: true
---
import { Steps } from '@astrojs/starlight/components';

你可以透過 [GitHub Pages](https://pages.github.com/) 直接從 [GitHub](https://github.com/) 的儲存庫中部署你的 Astro 網站。
你可以使用 [GitHub Pages](https://pages.github.com/) 透過 [GitHub Action](https://github.com/features/actions) 直接從 [GitHub.com](https://github.com/) 的儲存庫架設靜態、預先算繪的 Astro 網站。

## 如何部署

你可以透過 [GitHub Actions](https://github.com/features/actions) 自動將 Astro 網站搭建並部署到 GitHub Pages 上。正因如此，網站的原始碼必須要放在 Github 上。
Astro 維護了[官方的 Astro GitHub Action 用於部署專案至 GitHub Pages](https://github.com/withastro/action)，只需要極少的設定，這是官方推薦的 GitHub Pages 部署方式。

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

## 在 Github Pages 設定 Astro

### 部署至 `github.io` 網址

請在 `astro.config.mjs` 組態檔中設定 [`site`](/zh-tw/reference/configuration-reference/#site) 與 [`base`](/zh-tw/reference/configuration-reference/#base) 兩個選項。

```js title="astro.config.mjs" ins={4-5}
import { defineConfig } from 'astro/config'

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

#### `site`

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

- 以你的使用者名稱產生的網址，如：`https://<username>.github.io`
- 為 [GitHub 組織的不公開頁面](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site)所產生的亂數網址，如：`https://<random-string>.pages.github.io/`

#### `base`

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

:::note
如果你的情況符合以下其中之一，請不要設定 `base` 參數：

- 如果你的頁面由根資料夾所提供。
- 如果你的原始碼儲存庫在 `https://github.com/<USERNAME>/<USERNAME>.github.io`。
:::

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

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

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

你可以在[設定 `base` 值](/zh-tw/reference/configuration-reference/#base)中找到更多相關資訊。
:::

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

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

```js title="public/CNAME"
sub.mydomain.com
```

這會將網站部署在所指定的自訂網域名稱下，而非 `<YOUR_USERNAME>.github.io`。不要忘記[為你的域名提供商設定 GitHub Pages](https://docs.github.com/cn/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain)。
:::

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

```js title="astro.config.mjs" ins={4}
import { defineConfig } from 'astro/config'

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

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

<Steps>
1. 在專案的 `.github/workflows/` 資料夾中建立名為 `deploy.yml` 的新檔案，並將以下 YAML 設定貼進其中。
1. 在專案內新增 `.github/workflows/deploy.yml` 檔案，並貼上下面的 YAML。

```yaml title="deploy.yml"
name: Deploy to GitHub Pages

on:
# 在每次推送到 `main` 分支時觸發部署
# 如果你想要在其他分支上觸發部署，請將 `main` 替換成你想要的分支名稱
# 在每次推送到 `main` 分支時觸發 workflow
# 如果你想要在別的分支上觸發，請將 `main` 替換成你想要的分支名稱
push:
branches: [ main ]
# 允許你在 GitHub 上的 Actions 分頁中手動觸發此部署
# 允許你在 GitHub 上的 Actions 分頁中手動觸發這個 workflow
workflow_dispatch:

# 允許這個工作複製儲存庫並建立頁面部署
Expand All @@ -112,13 +43,16 @@ export default defineConfig({
runs-on: ubuntu-latest
steps:
- name: Checkout your repository using git
uses: actions/checkout@v4
uses: actions/checkout@v6
- name: Install, build, and upload your site
uses: withastro/action@v3
uses: withastro/action@v6
# with:
# path: . # 儲存庫中 Astro 專案的根位置。（可選）
# node-version: 20 # 用於建置網站的特定 Node.js 版本，預設為 20。（可選）
# node-version: 24 # 用於建置網站的特定 Node.js 版本，預設為 22。（可選）
# package-manager: pnpm@latest # 應該使用哪個 Node.js 套件管理器來安裝相依套件和建置網站，會根據儲存庫中的 lockfile 自動檢測。（可選）
# build-cmd: pnpm run build # 用來建置網站的指令。預設會執行套件的建置腳本／任務。（可選）
# env:
# PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # 變數的值請用單引號括住（可選）

deploy:
needs: build
Expand All @@ -129,43 +63,103 @@ export default defineConfig({
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
uses: actions/deploy-pages@v5
```

:::note
Astro GitHub Action 允許提供幾個選項，例如 `path`、`node-version` 和 `package-manager`。這些選項是可選的，可以透過解除註解 `with:` 行與你需要啟用的選項行來改變這些選項的設定。
:::
你可以透過可選的輸入設定 Astro action。若要提供這些參數，請取消註解 `with:` 這一行，以及你想要使用的輸入。
如果網站需要任何公開的環境變數，請取消註解 `env:` 這一行，並在這裡加入。（要加入私密的環境變數，請參見 [GitHub 關於設定秘密的文件](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository)。）

:::caution
官方提供的 Astro [GitHub Action](https://github.com/withastro/action) 會透過掃描根目錄下的 lockfile 來檢查你所使用的套件管理器（如 `npm`、`yarn`、`pnpm` 或 `bun`）。正因如此，你應該將套件管理器自動產生的 `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml` 或是 `bun.lockb` 檔案一起提交至你的儲存庫中。
官方的 Astro [action](https://github.com/withastro/action) 會掃描 lockfile 來偵測你偏好的套件管理器（`npm`、`yarn`、`pnpm` 或 `bun`）。你應該將套件管理器自動產生的 `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml` 或是 `bun.lockb` 檔案一起提交至儲存庫。
:::

2. （可選）如果你要在本地開發或預覽建置時傳遞環境變數到 Astro 專案，你需要在 `deploy.yml` 檔案定義所有公開的變數，這樣它們才會在部署至 GitHub Pages 時被處理。（要新增不公開的環境變數，請參閱 [GitHub 文件中關於設定秘密的部分](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository)。）
2. 在 Astro 設定檔，將 [`site`](/zh-tw/reference/configuration-reference/#site) 設為你要部署網站的 GitHub URL。

```yaml title="deploy.yml"
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
env:
# 對變數的值使用單引號
PUBLIC_EVM_WALLET_ADDRESS: '0x4bFc229A40d41698154336aFF864f61083E76659'
```
```js title="astro.config.mjs" ins={4}
import { defineConfig } from 'astro/config'

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

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

3. 在 GitHub 網站上，請切換到儲存庫中的 **Settings** 分頁，並找到 **Pages** 部分。
- 根據你的使用者名稱產生的下列 URL：`https://<username>.github.io`
- 為 [GitHub 組織私人頁面](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site) 自動產生的隨機 URL：`https://<random-string>.pages.github.io/`

4. 選擇 **GitHub Actions** 作為設定中的 **Source**。
3. 在 `astro.config.mjs`，為 [`base`](/zh-tw/reference/configuration-reference/#base) 設定一個值（通常需要）。

5. 將先前設定好的 workflow file 提交（Commit）並推送（Push）到 GitHub。
</Steps>
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`）：

```js title="astro.config.mjs" ins={4-5}
import { defineConfig } from 'astro/config'

恭喜你！如此一來，你的 Astro 網站就會自動部署到 GitHub Pages 上了。如果你更改了你的網站原始碼並推送到前述的儲存庫，GitHub Actions 也會自動重新構建並部署你的網站，你不需要手動構建和部署。
export default defineConfig({
site: 'https://astronaut.github.io',
base: '/my-repo',
})
```

:::caution[`base` 設定後的內部連結]
這個值設定後，所有內部頁面連結必須加上 `base` 值作為前綴：

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

查看更多關於[設定 `base` 值](/zh-tw/reference/configuration-reference/#base)的資訊。
:::

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

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

</Steps>

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

## 更改 GitHub URL 至自訂網域

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

<Steps>

1. [在你的網域供應商設定 DNS](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain)。
2. 將 `./public/CNAME` 記錄新增至專案中。

在 `public/` 資料夾建立以下檔案，裡面包含一行指定自訂網域的文字：
```js title="public/CNAME"
sub.example.com
```

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

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

```js title="astro.config.mjs" ins={4} del={5}
import { defineConfig } from 'astro/config'

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

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

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

</Steps>

## 範例

- [Github Pages 部署範例](https://github.com/hkbertoson/github-pages)
- [Github Pages 部署起始模板](https://github.com/hkbertoson/github-pages)
- [Starlight Flexoki 主題（正式站台）](https://delucis.github.io/starlight-theme-flexoki/)
- [Expressive Code Color Chips（正式站台）](https://delucis.github.io/expressive-code-color-chips/)
- [Starlight Markdown Blocks（正式站台）](https://delucis.github.io/starlight-markdown-blocks/)
Loading