Astro GitHub Actions

Astro GitHub Actions 是做什么的？

此技能可帮助你使用 GitHub Actions 为 Astro 站点设置全面的 CI/CD 流水线。目标是帮助作者以更少的手动工作发布更高质量的站点：在合并前捕获类型错误、标记断链、验证构建并自动部署。

此技能涵盖的内容

一个健康的 Astro 项目应该包含几类工作流。并非所有站点都需要全部类型的检查——最佳组合取决于项目是否使用了 TypeScript、自定义组件、内容集合、测试以及部署位置。你的工作是确定哪些检查是相关的并进行配置。

这些工作流分为以下几类：

1. 类型/内容检查 — astro check（TypeScript + 内容集合 schema 验证）
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 模板和配置文件。

如何处理请求

第一步：了解项目

在编写任何工作流文件之前，了解你正在处理的内容：

• 是否为 TypeScript？ 检查是否存在 tsconfig.json 和 .ts/.astro 文件。几乎每个 Astro 项目都应运行 astro check，但当 .astro frontmatter、内容集合 schema 或 src/ 中使用 TypeScript 时，其价值最高。
• 是否使用了内容集合？ 检查是否存在 src/content/config.ts 或 src/content.config.ts。如果是，astro check 将验证 schema——这非常有价值。
• 是否有测试？ 检查是否存在 tests/、__tests__/、*.test.ts 或 vitest.config.ts。如果是，请设置 Vitest 工作流。如果没有，建议添加测试会很有价值，但不要强制。
• 使用什么包管理器？ 查找 pnpm-lock.yaml、yarn.lock 或 package-lock.json。匹配工作流的 install 命令（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' 或导入的适配器。SSR 项目的部署方式不同（Cloudflare/Netlify/Vercel 适配器），并且可能根本无法部署到 GitHub Pages。

第二步：推荐一组工作流

根据你发现的情况，推荐要设置哪些工作流。对于大多数 Astro 站点，一个良好的默认集合是：

• astro check（几乎总是——这是 Astro 最有价值的检查）
• 构建验证（几乎总是——捕获 astro check 可能遗漏的集成回归）
• ESLint + Prettier（如果配置文件存在或用户需要）
• Lighthouse CI（非常适合具有公共 URL 的内容站点）
• 链接检查器（非常适合内容密集的站点）
• npm audit（成本低，几乎总是值得）

以及条件性的：

• Vitest 测试（如果测试存在）
• 部署工作流（仅当用户希望由 Actions 驱动部署时——大多数 Astro 托管平台使用自己的 GitHub 应用）

第三步：创建工作流文件

将每个工作流创建为 .github/workflows/ 下的独立 YAML 文件。使用单独的文件而不是一个单一的大型工作流，可以在 PR 中提供更清晰的反馈（每个检查独立显示），并且更容易启用或禁用单个检查。

使用 references/workflows.md 中的模板作为起点，但要根据具体项目进行调整。常见的调整包括调整包管理器、Node 版本、构建产物路径和部署目标。

第四步：创建支持配置文件

根据你设置的工作流，你可能还需要：

• eslint.config.js — 使用 eslint-plugin-astro 的 ESLint 扁平配置
• .prettierrc 和 .prettierignore — 使用 prettier-plugin-astro 的 Prettier 配置
• lighthouserc.json — Lighthouse CI 断言
• lychee.toml — 链接检查器配置（如果使用 lychee）
• vitest.config.ts — Vitest 配置

第五步：设置密钥提醒

如果你添加了部署工作流，请提醒用户需要哪些仓库密钥：

• 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

引导用户操作：仓库设置 > 密钥和变量 > Actions > 新建仓库密钥。

对于 Cloudflare、Netlify 和 Vercel：还要提醒他们，这些平台提供了自己的 GitHub 应用，可以自动处理构建、部署和 PR 预览。仅当需要将部署限定在测试结果之后、使用平台没有的密钥运行构建，或者从仓库根目录以外的路径部署时，基于 Actions 的部署才通常值得使用。

命名约定

使用描述性的工作流文件名，使其功能一目了然：

• astro-check.yml — astro check（类型 + 内容 schema）
• 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 源码运行会遗漏生成的路由和 sitemap 链接。

优先使用平台的 GitHub 应用而非 Actions 部署：Cloudflare Pages、Netlify 和 Vercel 都有第一方 GitHub 应用，它们处理 PR 预览、分支部署和回滚比手工编写的 Action 更好。首先推荐 GitHub 应用；仅当用户有特定理由时才建议使用 Actions 部署。