diff --git a/src/content/docs/zh-tw/guides/deploy/github.mdx b/src/content/docs/zh-tw/guides/deploy/github.mdx index 7d5ddcb7ecb3d..89ad937e3b4c8 100644 --- a/src/content/docs/zh-tw/guides/deploy/github.mdx +++ b/src/content/docs/zh-tw/guides/deploy/github.mdx @@ -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://.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://.pages.github.io/` - -#### `base` - -你可能需要設定 `base`，這樣 Astro 才會將儲存庫名稱（例如 `/my-repo`）視為網站的根目錄。 - -:::note - 如果你的情況符合以下其中之一，請不要設定 `base` 參數： - -- 如果你的頁面由根資料夾所提供。 -- 如果你的原始碼儲存庫在 `https://github.com//.github.io`。 -::: - -`base` 的內容應該是你的儲存庫名稱，並以正斜線開頭，例如 `/my-blog`。這樣做是為了讓 Astro 理解你的網站根目錄是 `/my-repo`，而不是預設的 `/`。 - -:::caution - 當設定了這個值後，你所有的內部頁面連結都必須以所設定的 `base` 值作為前綴： - -```astro ins="/my-repo" -關於本站 -``` - -你可以在[設定 `base` 值](/zh-tw/reference/configuration-reference/#base)中找到更多相關資訊。 -::: - -### 使用自定義網域名稱的 GitHub Pages - -:::tip[設定自訂網域] -你可以透過在專案建立 `./public/CNAME` 檔案來設定自訂網域名稱： - -```js title="public/CNAME" -sub.mydomain.com -``` - -這會將網站部署在所指定的自訂網域名稱下，而非 `.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://.github.io/`）的網站。部署完成後，你可以選擇[設定自訂網域](#更改-github-url-至自訂網域)，將 GitHub Pages 網站部署到你偏好的網域（例如 `https://example.com`）。 -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: # 允許這個工作複製儲存庫並建立頁面部署 @@ -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 @@ -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://.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://.pages.github.io/` -4. 選擇 **GitHub Actions** 作為設定中的 **Source**。 +3. 在 `astro.config.mjs`，為 [`base`](/zh-tw/reference/configuration-reference/#base) 設定一個值（通常需要）。 -5. 將先前設定好的 workflow file 提交（Commit）並推送（Push）到 GitHub。 - + GitHub Pages 發佈網站的網址取決於你的使用者名稱與儲存庫名稱（例如 `https://.github.io//`）。請為 `base` 設定一個值來為網站指定儲存庫。這是為了讓 Astro 了解網站的根目錄是 `/my-repo` 而不是預設的 `/`。如果你的儲存庫名稱符合特殊的 `.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" + 關於 + ``` + + 查看更多關於[設定 `base` 值](/zh-tw/reference/configuration-reference/#base)的資訊。 + ::: + +4. 在 GitHub 網站上，請切換到儲存庫中的 **Settings** 分頁，並找到 **Pages** 部分。 + +5. 選擇 **GitHub Actions** 作為網站的 **Source**。 + + + +當你推送變更到 Astro 專案的儲存庫，GitHub Action 會自動將它們部署到你的 GitHub URL 上。 + +## 更改 GitHub URL 至自訂網域 + +一旦你跟著前面的指示將 Astro 專案[部署到 GitHub pages 的 GitHub URL](#如何部署) 後，你就可以設定自訂網域。這代表使用者可以透過自訂網域 `https://example.com` 來造訪你的網站，而不是 `https://.github.io`。 + + + +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" + 關於 + ``` + + ## 範例 -- [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/)