astro-seo

Astro SEO

根据 Astro SEO：权威指南 中描述的完整技术栈，审核并改进 Astro 网站的 SEO 设置。这项技能涵盖九个方面——技术基础、结构化数据、内容、网站结构、性能、站点地图与索引、Agent 发现、重定向和分析——并为任何缺失或薄弱的部分生成可直接使用的代码。

这项技能的核心方案是 @jdevalk/astro-seo-graph。大部分修复都通过它实现。如果项目尚未使用它，首要建议就是安装它。

代码示例位于 AGENTS.md——需要实现具体修复时，请阅读该文件。本文包含工作流和审核清单。

工作流

1. 检测项目——确认这是一个 Astro 网站并了解其结构。
2. 审核——为九个类别评分并列出可执行的发现。
3. 改进——生成或修改文件以弥补差距。代码示例见 AGENTS.md。
4. 元数据检查——对技能生成的每个短字符串调用 metadata-check（标题、描述、结构化数据中的 description 字段、FAQ 答案、frontmatter 摘录）。
5. 验证——运行构建，检查验证是否通过，并提醒用户处理非文件任务（Search Console、Bing Webmaster Tools、IndexNow 密钥验证）。

---

阶段 0：检测项目

审核前确认以下基本信息：

• 存在 astro.config.mjs / astro.config.ts。
• package.json 将 astro 列为依赖项。
• astro.config 中已设置 site:——规范链接、站点地图和 OG 图片 URL 都由此生成。如果缺失、为空或设为 http://localhost，应先将其标记为阻塞性问题，再进行其他检查。这是最常见的配置错误。
• src/content/ 中的内容集合（或旧版 src/pages/ Markdown 文件）。
• 部署目标——读取 package.json、vercel.json、netlify.toml、wrangler.toml 或 public/_headers，以确定主机。阶段 2 中的重定向和标头语法取决于此。
• 是否已安装 @jdevalk/astro-seo-graph？ 如果已安装，记录版本以及已接入的功能（搜索 <Seo、seoGraph(、createSchemaEndpoint、createSchemaMap、FuzzyRedirect、createIndexNowKeyRoute、createMarkdownEndpoint、createApiCatalog、gitLastmod）。使用 npm view @jdevalk/astro-seo-graph version 检查已安装版本是否为 npm 上的最新版本。 如果项目版本落后，应在阶段 2 审核功能差距前建议升级——该软件包会定期发布新的默认设置和修复，版本过旧可能导致任何审核发现的问题。阶段 2 会根据此项分支处理。
• 网站是否支持多语言？ 检查 astro.config 中是否有 i18n，或 src/content/ 下是否有多个区域目录。如果是，hreflang 就很重要；如果不是，则跳过。

只询问无法检测到的信息。不要询问用户网站的主题——请阅读 astro.config.mjs 和首页内容。

---

阶段 1：审核

每个类别按 10 分制评分。每个类别给出 2–4 条具体发现，并引用实际代码或配置。每个类别中的检查分为以下等级：

• 必须——上线阻塞项。此处未通过会导致明显的 SEO 表现下降。
• 应该——标准做法。忽略会损失覆盖面。
• 可选——面向未来或视情况适用。有用，但并非所有网站的基础要求。

除非用户要求完整检查，否则小型个人博客可跳过可选检查。

1. <Seo> 组件和 head 元数据（/10）

• 必须 — 所有 head 元数据都由单个组件处理（而非分散在各个布局中）。
• 必须 — astro.config 中的 site: 设置为生产环境源站。
• 必须 — 规范 URL 根据 site 配置生成，并去除跟踪参数。
• 必须 — 当 noindex 为 true 时省略规范 URL（遵循 Google 的建议）。
• 必须 — SEO 字段缺失时的回退链：seo.title → title → siteName；seo.description → excerpt → first paragraph。标题或描述为空的页面，是回退机制失效最常见的表现。
• 应该 — robots 元标签包含 max-snippet:-1、max-image-preview:large、max-video-preview:-1。
• 应该 — 当 Twitter 标签与 Open Graph 重复时，不输出 Twitter 标签（Twitter 会自动回退）。
• 应该 — 多语言站点应提供 hreflang 替代项。单语站点可跳过。
• 可选 — 使用 @jdevalk/astro-seo-graph 的 <Seo> 组件，而不是手动实现。（手动实现且涵盖上述所有内容也可以；本技能推荐使用该软件包，因为它默认处理回退链和 robots 规则。）

2. 结构化数据 / JSON-LD 图（/10）

• 使用单个扁平的 Article 对象，还是包含多个实体的关联 @graph？
• 实体之间是否通过 @id 引用关联？
• 是否在适用的情况下包含 WebSite、Blog/WebPage、Person/Organization、BlogPosting/Article、BreadcrumbList、ImageObject？
• 信任信号：publishingPrinciples、copyrightHolder、copyrightYear、knowsAbout、SearchAction？
• 能否通过 Rich Results 测试 和 ClassySchema 验证？

3. 内容集合和 SEO 架构（/10）

• 是否使用 Zod 架构定义内容集合？
• 是否通过 @jdevalk/astro-seo-graph 的 seoSchema 限制标题（5–120）和描述（15–160）的长度？
• 是否在构建时强制要求必填字段（publishDate、title、excerpt）？
• 是否在架构端点中提供去除 Markdown 标记的 articleBody（最多 10K 个字符）？

4. Open Graph 图片（/10）

• 每个页面都有 OG 图片，还是有很多页面缺少图片？
• 尺寸是否为 1200×675（Google Discover 要求宽度至少为 1200px，宽高比为 16:9）？
• 是否通过 satori + sharp 在构建时生成，还是手动制作？
• 是否为 JPEG（社交平台对 WebP/AVIF 的支持并不可靠）？
• 路由是否根据 slug 自动生成 OG URL？
• 渲染后的 HTML 中，每个 <img> 是否都有 alt 属性（装饰性图片使用 alt="" / role="presentation"）？在 ≥ 1.1.0 版本中，seoGraph() 上的 validateImageAlt 会在构建时检查这一点。

5. 站点地图和索引（/10）

• 必须 — 已安装 @astrojs/sitemap，且可访问站点地图索引。
• 必须 — robots.txt 中引用了站点地图索引。
• 必须 — 存在 RSS 订阅源（@astrojs/rss），通过 <link rel="alternate" type="application/rss+xml"> 声明，并包含完整文章内容（而非截断的摘要）。
• 应当 — 使用 chunks 选项按集合拆分（sitemap-posts-0.xml 等）——这会让在 GSC 中调试索引容易得多。
• 应当 — lastmod 根据 git 提交时间戳填充，而非 frontmatter 日期或 CI 文件时间戳。@jdevalk/astro-seo-graph ≥ 1.4.0 导出了 gitLastmod(filePath, { excludeCommits, depth })，可用于此目的——它会返回最近一次修改该文件的未排除提交的提交者日期；如果 git 不可用，则返回 null。将其接入站点地图的 serialize 回调。如果代码库中有手写的 execSync('git log ...') 辅助函数，请用该包的导出替换——该导出会处理批量提交排除（导入、重新格式化），而简单的 -1 查询无法做到。
• 应当 — 集成 IndexNow，并在每次构建时提交；密钥验证路由为 /[key].txt。≥ 1.0.1 默认会排除 /404，不将其纳入提交。仅在生产主机上提交（例如，process.env.CF_PAGES === '1' && CF_PAGES_BRANCH === 'main'、VERCEL_ENV === 'production'、CONTEXT === 'production'）。无条件提交会在每次本地 npm run build 和预览部署时 ping 该端点，提交生产主机尚未提供的 URL，导致密钥被标记为无效（403），必须轮换密钥。

6. Agent 发现（/10）

• 应做 — 架构端点（/schema/*.json）公开整个语料库的 JSON-LD。
• 应做 — 架构映射（/schemamap.xml）列出所有端点，并在 robots.txt 中加入 Schemamap: 指令。
• 应做 — 在网站根目录提供 llms.txt，列出供大模型使用的页面（标题 + 描述）。@jdevalk/astro-seo-graph ≥ 0.9.0 可通过 llmsTxt 集成选项生成此文件。
• 应做 — 提供 Markdown 替代 URL（/blog/post/ 旁的 /blog/post.md），以 YAML frontmatter 提供整洁的 Markdown 内容，供 AI Agent 使用，无需解析 HTML。@jdevalk/astro-seo-graph ≥ 1.2.0 提供用于路由的 createMarkdownEndpoint，以及会在每个页面输出 <link rel="alternate" type="text/markdown"> 的 markdownAlternate: true 集成选项。≥ 1.3.0 增加了构建后验证：集成会遍历构建输出，并移除目标 .md 文件不存在的链接（每次出现都会发出一条 warn）——因此，配置错误的端点会导致构建警告，而不是发布后产生 404。可搭配 Cloudflare Transform Rule（通过 wildcard_replace 重写 URL，不设置 Vary: Accept 标头——CF 会剥除自定义 Vary 值），根据 Accept: text/markdown 协商内容，无需 SSR。
• 应做 — 按照 RFC 9727，在 /.well-known/api-catalog 提供 API 目录。@jdevalk/astro-seo-graph ≥ 1.4.0 提供 createApiCatalog，可自动将架构端点的类型映射到对应的 https://schema.org/<Type> URL，并根据 siteUrl 将路径转换为绝对路径。列出架构端点、架构映射以及任何站点专属 API（/ask、/feed.xml 等）。该 RFC 已定稿，格式稳定；目前采用尚处早期阶段，但只需添加一个路由文件。
• 应做 — 在 robots.txt 中加入 Content Signals 指令（例如：Content-Signal: ai-train=yes, search=yes, ai-input=yes）。该指令分别声明对 AI 训练、搜索依据和 AI 输入使用的偏好，不受爬取访问权限影响。规范仍是一个 IETF 草案，目前采用尚处早期阶段，但只需在每个网站都已有的文件中添加一行。
• 应做 — 在 /* 上设置 Link 标头，指向发现文件（站点地图、llms.txt、api-catalog、schemamap，以及网站发布的任何 MCP / A2A 卡片）。读取响应标头的 Agent 无需解析 HTML 即可找到这些文件。在 Cloudflare Pages / Netlify 上，这对应 public/_headers；在 Vercel 上则对应 vercel.json。
• 可选 — 在 /.well-known/mcp/server-card.json 提供 MCP 服务卡片（SEP-1649），和 / 或在 /.well-known/agent-card.json 提供 A2A Agent 卡片（A2A protocol）。仅当网站实际公开了 MCP 服务或 A2A Agent 时才相关。两者都是静态 JSON 文件，用于声明端点、功能和技能；否则可跳过。
• 可选 — 添加指向对话端点的 <link rel="nlweb">。NLWeb 尚处早期阶段；虽然只需添加一行，值得采用，但在 2026 年它并非评分的阻碍因素。
• 可选 — 在 /.well-known/ai-catalog.json 提供 ARD（Agentic Resource Discovery）目录，列出该域名提供的内容（MCP 服务、A2A Agent、OKF 包、站点专属 API）。目前是 v0.9 草案，因此可选；不过它是 MCP / A2A 卡片和 OKF 包发挥作用所需的发现层。有两点需注意：基础规范（Agent-Card/ai-catalog）将媒体类型字段命名为 mediaType，而 ARD 层（ards-project/ard-spec）将其命名为 type——请用相同的值输出两个键，确保条目符合任一规范的要求（两个规范都要求使用方忽略未知键）。ARD 还为每个条目增加了可选的 representativeQueries 数组，用于列出示例提示词。
• 可选 — OKF（Open Knowledge Format）包：由一组带类型的 Markdown 概念文件组成的目录树（每个页面一个文件，路径与规范 URL 对应），打包为单个 .tar.gz 文件，并在中间加入索引文件。OKF 明确不负责提供服务和发现功能——这些由 ARD 目录条目负责。目前是 v0.9 草案，可选。目前尚无注册的媒体类型，因此暂用 application/okf-bundle+gzip（由 knowledge-catalog#111 和 ard-spec#27 跟踪）；请标明这是临时方案，之后可能会变更。最好将其作为现有内容管线的另一个输出生成，而不是手动维护一份副本。

7. 性能（/10）

• 默认使用静态输出（不需要 SSR 的页面不使用 SSR）？
• 除非需要岛屿，否则客户端 JS 为零？
• 所有内容图片都使用 Astro <Image> 组件（响应式 srcset、WebP、懒加载、异步）？
• 预加载 woff2 格式的主要网页字体？
• 使用 <ClientRouter />，并将 defaultStrategy 设为 'viewport' 以进行预取？
• /_astro/ 下的带哈希资源是否通过 Cache-Control: public, max-age=31536000, immutable 提供？
• No-Vary-Search 响应头是否会从缓存键中剔除 UTM 参数？

8. 重定向与错误处理（/10）

• 是否为所有曾经存在且已迁移的网址维护 public/_redirects（或等效配置）？
• 永久迁移是否使用 301 而非 302？
• 404 页面是否接入了 @jdevalk/astro-seo-graph 中的 FuzzyRedirect 组件？
• 404 页面本身是否返回 404 状态，而非 200？

9. 构建时验证与内容质量（/10）

• 必须 — 每次构建都运行 seoGraph() 集成，并启用 validateH1 和 validateUniqueMetadata。验证 JSON-LD 时，在 seo-graph-core 的 assembleGraph() 中传入 warnOnDanglingReferences: true——这是组装时检查，不是集成选项。
• 应当 — 在 seoGraph() 上启用 validateImageAlt、validateMetadataLength 和 validateInternalLinks（在 ≥ 1.1.0 中默认均为 true）。它们可以检测缺失的替代文本、超出 SERP 范围的标题或描述（默认范围：标题 30–65，描述 70–200），以及会导致 404 或尾部斜杠不匹配的内部链接。如果项目使用的是 1.1.0，请升级至 ≥ 1.1.1——此补丁版本修复了两个验证器错误：validateInternalLinks 现在会将 public/ 资源识别为有效目标（不再对 /images/* 或 /fonts/* 产生误报），而 validateMetadataLength 不再截断包含原始撇号的描述。仅对 SSR 专用路由、通配符和 [slug] 参数使用 skip。
• 应当 — 在 CI 中检查失效的_外部_链接。在每次推送内容文件时运行 lychee GitHub Action，可在失效链接上线前将其查出；每周定时运行则可在外部网站迁移或消失时发现链接失效。失效的外链会损害用户体验，也会降低信任度。内部链接由构建时的 validateInternalLinks 检查；其余链接则由 lychee 处理。
• 应当 — 审核 SEO 文案（标题、描述、常见问题解答），确保元数据质量，包括重点前置、内容具体、适合截断，且标题与描述不重复。Phase 2.5 会通过 metadata-check 将此项检查纳入流程。单篇文章正文可通过 readability-check 单独审核。

---

阶段 2：改进

根据审计结果生成具体代码。覆盖内容前务必先询问。阅读 AGENTS.md 获取详细操作步骤。

根据 Phase 0 的发现调整操作。 如果已安装 @jdevalk/astro-seo-graph，则跳过安装步骤，重点接入审计中发现缺失的功能（IndexNow、FuzzyRedirect、Schema 端点、构建验证）。如果用户手动搭建的配置已满足类别 1 中的必须项，不要将其替换——只补充缺失的部分。替换是最后手段，而非默认做法。

AGENTS.md 章节：安装/升级、集成配置、BaseHead.astro、内容集合 schema、站点地图 + git lastmod、OG 图片路由、Schema 端点、llms.txt、Markdown alternate、API 目录、robots.txt 中的 Content Signals、MCP 和 A2A 发现卡片、用于 Agent 发现的 Link 头、RSS feed、重定向 + FuzzyRedirect、性能响应头、CI 中的失效链接检查。

---

阶段 2.5：元数据与可读性检查

对该技能生成或修改的每条短文本运行 metadata-check 技能：页面标题、元描述、架构 description 字段、FAQ 答案，以及你编写的任何博客文章 frontmatter excerpt 值。该技能会检查信息前置、具体性、填充内容、主动语态、标题与描述是否重复、用词是否晦涩、是否适合 SERP 截断（标题 30–65 个字符，描述 70–200 个字符——与 validateMetadataLength 强制执行的范围相同），以及每个字段是否只表达一个观点。直接应用修改。技术字符串（URL、架构 @id 值、枚举值）完全跳过此检查。

如果项目有博客或文档内容集合，请在后续告知用户，readability-check 技能可以逐篇检查文章的多段落文案质量——但不要自行审查整个内容库。

---

阶段 3：验证

• 运行 npm run build。如果已接入 seoGraph()，此步骤也会运行 H1 验证、重复元数据检测和架构验证——请指出任何警告。
• 抽查构建后的 HTML：任选一个页面，其 <head> 应当整洁，规范链接应当正确，JSON-LD 图谱应当存在并已关联。
• 使用 Rich Results Test 和 ClassySchema 测试首页。
• 确认 /sitemap-index.xml 存在，并且引用了各内容集合的站点地图。
• 如果已接入 IndexNow，请确认密钥验证路由在 /[key].txt 返回密钥。
• 提醒用户处理无法自动化的任务：
  • 在 Google Search Console 和 Bing Webmaster Tools 中注册网站。
  • 在两者中提交站点地图索引。
  • 生成 IndexNow 密钥并将其提交到配置中。
  • 安装 Plausible 或同类注重隐私的分析工具。

---

输出格式

## Astro SEO audit: [site name]

### Score
| Category                              | Score |
|---------------------------------------|------:|
| 1. `<Seo>` component and head         |  x/10 |
| 2. Structured data / JSON-LD graph    |  x/10 |
| 3. Content collections and schema     |  x/10 |
| 4. Open Graph images                  |  x/10 |
| 5. Sitemaps and indexing              |  x/10 |
| 6. Agent discovery                    |  x/10 |
| 7. Performance                        |  x/10 |
| 8. Redirects and error handling       |  x/10 |
| 9. Build-time validation and content  |  x/10 |
| **Total**                             | xx/90 |

### Findings
[Grouped by category. Quote actual code/config. Be specific.]

### Files generated or changed
[List with short description of each.]

### Next steps
[Non-file tasks: GSC, Bing Webmaster Tools, IndexNow key generation, analytics.]

---

核心原则

• 采用有主见的默认方案，而非提供过多选择。 本指南选择技术栈；此技能负责应用它。一个方案可行时，不要提供五种替代方案。
• @jdevalk/astro-seo-graph 是核心。 除非用户有充分理由选择自行实现，否则应通过它接入 <Seo> 组件、架构端点、IndexNow、FuzzyRedirect 和构建验证。
• 关注主题，而非关键词短语。 审阅内容时，应着重关注主题覆盖和可读性，而非关键词密度。
• 静态且由 CDN 提供的 HTML 是基准方案。 不要为了处理静态构建本就能解决不了的问题而添加 SSR。
• Agent 发现能力如今很重要。 架构端点、架构映射、NLWeb 标签——爬虫不再是唯一的内容使用者。