astro-github-actions

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 adapter），而且可能无法部署到 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

引导他们依次前往：Repository Settings > Secrets and variables > Actions > New repository secret。

对于 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 的稳定目标版本，许多适配器也都针对它进行了测试。使用 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 适配器和 SSR：如果项目使用 @astrojs/cloudflare、@astrojs/netlify 或 @astrojs/vercel，构建输出可能不是静态的 dist/ 目录。Cloudflare 适配器会输出 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，以获得真实的指标。对于仅限内部使用的方案，可在运行器中本地构建并提供服务。

检查构建输出中的链接，而非源文件：对构建后的 dist/ 目录运行链接检查工具（或检查已部署的预览 URL）——检查 Markdown 源文件会漏掉生成的路由和站点地图链接。

优先使用平台的 GitHub 应用，而非通过 Actions 部署：Cloudflare Pages、Netlify 和 Vercel 都提供官方 GitHub 应用，在处理 PR 预览、分支部署和回滚方面都优于手动编写的 Action。首先推荐使用 GitHub 应用；只有用户有特定理由时，才建议使用 Actions 部署。