jdevalk/skills

Astro GitHub Actions

此技能可協助您使用 GitHub Actions 為 Astro 網站設定全面的 CI/CD 管線。目標是幫助作者以更少的手動工作，產出更高品質的網站：在合併前捕捉型別錯誤、標記損壞的連結、驗證建置，並自動化部署。

此技能涵蓋的內容

一個健康的 Astro 專案應具備幾個類別的工作流程。並非每個網站都需要所有項目 — 正確的組合取決於專案是否使用 TypeScript、自訂元件、內容集合、測試以及部署位置。您的工作是判斷哪些是相關的，並進行設定。

工作流程分為以下類別：

1. 型別/內容檢查 — astro check（TypeScript + 內容集合結構驗證）
2. 程式碼品質 — ESLint 和 Prettier
3. 建置驗證 — astro build 能順利執行
4. 測試 — 用於單元測試和元件測試的 Vitest
5. 品質把關 — Lighthouse CI（效能、無障礙性、SEO、最佳實務）
6. 連結檢查 — 對已建置網站進行損壞連結偵測
7. 安全性 — 用於相依性漏洞檢查的 npm audit
8. 部署 — GitHub Pages、Cloudflare Pages、Netlify 或 Vercel

請參閱 references/workflows.md 以了解每個工作流程的詳細配置，包括可直接使用的 YAML 範本和設定檔。

如何處理請求

步驟 1：了解專案

在撰寫任何工作流程檔案之前，請先了解您正在處理的內容：

• 是否使用 TypeScript？ 檢查 tsconfig.json 以及 .ts/.astro 檔案。幾乎每個 Astro 專案都應執行 astro check，但當 .astro frontmatter、內容集合結構或 src/ 中有 TypeScript 時，其價值最高。
• 是否使用內容集合？ 檢查 src/content/config.ts 或 src/content.config.ts。如果是，astro check 會驗證其結構 — 這額外有價值。
• 是否有測試？ 檢查 tests/、__tests__/、*.test.ts 或 vitest.config.ts。如果是，請設定 Vitest 工作流程。如果沒有，可以提及新增測試會很有價值，但不要強制執行。
• 使用哪個套件管理器？ 尋找 pnpm-lock.yaml、yarn.lock 或 package-lock.json。比對工作流程中的安裝指令（pnpm i --frozen-lockfile、yarn install --frozen-lockfile 或 npm ci）。
• 部署到哪裡？ 尋找 wrangler.toml（Cloudflare）、netlify.toml（Netlify）、vercel.json（Vercel），或直接詢問。大多數主機都有自己的 GitHub 應用程式，可以在沒有 Actions 的情況下自動部署 — 僅在使用者確實希望 Actions 處理部署時（通常是 GitHub Pages 或自架主機），才設定部署工作流程。
• 是否有建置步驟？ Astro 總是有的（astro build）— 但請驗證 package.json 中的腳本是否為標準的 astro build，而非自訂腳本。
• 是 SSR 還是靜態？ 檢查 astro.config.* 中是否有 output: 'server' 或 adapter 匯入。SSR 專案的部署方式不同（使用 Cloudflare/Netlify/Vercel adapters），並且可能完全無法部署到 GitHub Pages。

步驟 2：推薦一組工作流程

根據您的發現，推薦要設定的工作流程。對於大多數 Astro 網站來說，一個好的預設組合是：

• astro check（幾乎總是 — 這是 Astro 最有價值的檢查）
• 建置驗證（幾乎總是 — 能捕捉到 astro check 可能遺漏的整合性回歸問題）
• ESLint + Prettier（如果設定檔存在或使用者想要）
• Lighthouse CI（非常適合具有公開 URL 的內容網站）
• 連結檢查器（非常適合內容豐富的網站）
• npm audit（成本低，幾乎總是值得）

以及條件性的：

• Vitest 測試（如果測試存在）
• 部署工作流程（僅在使用者想要由 Actions 驅動的部署時 — 大多數 Astro 主機使用自己的 GitHub 應用程式）

步驟 3：建立工作流程檔案

將每個工作流程建立為 .github/workflows/ 中的獨立 YAML 檔案。使用獨立檔案而非單一的大型工作流程，可以在 PR 中提供更清晰的回饋（每個檢查獨立顯示），並更容易啟用或停用個別檢查。

使用 references/workflows.md 中的範本作為起點，但根據特定專案進行調整。常見的調整包括調整套件管理器、Node 版本、建置產物路徑和部署目標。

步驟 4：建立支援設定檔

根據您設定的工作流程，您可能還需要：

• eslint.config.js — 使用 eslint-plugin-astro 的 ESLint flat config
• .prettierrc 和 .prettierignore — 使用 prettier-plugin-astro 的 Prettier 設定
• lighthouserc.json — Lighthouse CI 斷言
• lychee.toml — 連結檢查器設定（如果使用 lychee）
• vitest.config.ts — Vitest 配置

步驟 5：設定密碼提醒

如果您要新增部署工作流程，請提醒使用者需要哪些儲存庫密碼：

• GitHub Pages — 無（使用 GITHUB_TOKEN）
• Cloudflare Pages — CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID
• Netlify — NETLIFY_AUTH_TOKEN、NETLIFY_SITE_ID
• Vercel — VERCEL_TOKEN、VERCEL_ORG_ID、VERCEL_PROJECT_ID

引導他們：儲存庫設定 > Secrets and variables > Actions > 新增儲存庫密碼。

對於 Cloudflare、Netlify 和 Vercel：也提醒他們，這些平台本身就提供了自己的 GitHub 應用程式，可以自動處理建置、部署和 PR 預覽。基於 Actions 的部署通常只有在您需要根據測試結果來控制部署、使用平台沒有的密碼來執行建置，或從儲存庫根目錄以外的路徑部署時，才值得使用。

命名慣例

使用描述性的工作流程檔案名稱，讓人一看就知道每個檔案的作用：

• astro-check.yml — astro check（型別 + 內容結構）
• lint.yml — ESLint
• format.yml — Prettier 檢查
• build.yml — 建置驗證
• test.yml — Vitest
• lighthouse.yml — Lighthouse CI
• links.yml — 損壞連結檢查器
• security.yml — npm audit
• deploy.yml — 部署到主機

重要細節

Node.js 版本：Astro 需要 Node 18.20.8+、20.3.0+ 或 22.0.0+。預設使用 Node 22 — 它符合 Astro 的穩定目標版本，並且許多 adapter 都針對它進行了測試。使用 actions/checkout@v5 和 actions/setup-node@v5。

套件管理器偵測：始終比對鎖定檔案。pnpm-lock.yaml → 使用 pnpm/action-setup@v4 和 pnpm install --frozen-lockfile。yarn.lock → yarn install --frozen-lockfile。package-lock.json → npm ci。不要在 CI 中使用 npm install（非確定性、速度較慢）。

分支命名：大多數 Astro 儲存庫使用 main 作為預設分支，但請在撰寫觸發條件前檢查實際的儲存庫。

Astro adapters 和 SSR：如果專案使用了 @astrojs/cloudflare、@astrojs/netlify 或 @astrojs/vercel，建置輸出可能不是靜態的 dist/ 目錄。Cloudflare adapter 輸出 dist/ 加上一個 _worker.js；Vercel 輸出 .vercel/output/；Netlify 輸出 .netlify/。據此調整部署產物路徑。

astro check 需要 @astrojs/check 和 typescript：兩者都必須已安裝。如果它們不在 devDependencies 中，工作流程將會失敗。僅當它們已在 package.json 中時，才將它們作為 npm ci 的一部分新增 — 否則工作流程應明確安裝它們。

PR 上的 Lighthouse CI：在每個 PR 上執行 Lighthouse 可以及早捕捉效能回歸。treosh/lighthouse-ci-action 是標準做法。對於公開預覽 URL（Cloudflare Pages、Netlify、Vercel），將 Lighthouse 指向部署預覽 URL — 這能提供實際的數據。對於僅限內部的設定，請在 runner 內部建置並在本機提供服務。

對建置輸出進行連結檢查，而非原始碼：在已建置的 dist/ 目錄（或針對已部署的預覽 URL）上執行連結檢查器 — 對 Markdown 原始碼執行會遺漏產生的路由和網站地圖連結。

優先使用平台的 GitHub 應用程式而非 Actions 部署：Cloudflare Pages、Netlify 和 Vercel 都有第一方的 GitHub 應用程式，它們在處理 PR 預覽、分支部署和回滾方面，比手動編寫的 Action 更好。首先推薦 GitHub 應用程式；僅在使用者有特定理由希望以這種方式進行時，才建議使用 Actions 部署。