static-seo

静态 SEO

针对九个类别审查并改进静态 HTML 网站的 SEO 设置——head 元数据、结构化数据、内容质量、Open Graph 图片、站点地图和索引、Agent 发现、性能、重定向和 CI 验证。实现方案不依赖特定平台：原始 <meta> 标签、原始 JSON-LD、手动编写的 sitemap.xml、通用 CI 工具。审查框架与 astro-seo 类似，但不依赖 @jdevalk/astro-seo-graph 核心。

代码实现方案位于 AGENTS.md——需要实现特定修复时，请阅读该文件。本文件包含工作流和审查清单。

工作流

1. 检测项目 — 确认这是一个静态网站，识别构建工具，并找到应用更改的位置。
2. 审查 — 为九个类别评分，并给出可执行的发现。
3. 改进 — 生成或修改文件，以弥补差距。实现方案见 AGENTS.md。
4. 元数据检查 — 对本技能生成的每个短字符串（标题、描述、架构中的 description 字段、FAQ 答案）调用 metadata-check。
5. 验证 — 运行构建、验证输出，并提醒用户处理非文件任务（Search Console、Bing Webmaster Tools、提交 IndexNow 密钥）。

---

阶段 0：检测项目

审查前确认基本情况：

• 确认它确实是静态网站。 查找已构建的 HTML——仓库根目录下的 index.html，或 _site/（Jekyll）、public/（Hugo / 11ty / Gatsby）、dist/（Vite / Astro static）、out/（使用 output: export 的 Next.js）目录中的文件。如果所有内容都是服务端渲染的（Express、PHP、动态路由），则不适用此技能——Astro 项目请参阅 astro-seo，WP 插件页面请参阅 wp-readme-optimizer，或建议进行通用 SEO 审查。
• 源代码构建工具。 这决定了应用 head 元数据更改的位置：
  • _config.yml / _layouts/ → Jekyll
  • config.toml / config.yaml / themes/ → Hugo
  • .eleventy.js / _includes/ → 11ty
  • gatsby-config.js / src/components/SEO.* → Gatsby
  • 配置了 output: 'export' 的 next.config.js 和 pages/_document.tsx → Next.js 静态导出
  • astro.config.mjs → Astro（此时改用 astro-seo）
  • 没有构建配置，只有 HTML 文件 → 手动编写或抓取生成（例如 wp-static-clone 的输出）。直接编辑 HTML，或使用后处理脚本。
• 规范网站 URL。 在仓库中搜索生产环境的源站地址——通常位于 _config.yml、config.toml、astro.config 中，或硬编码在布局文件里。如果缺失、为空或为 localhost，请先将其标记为阻塞问题。 规范 URL、站点地图、OG 图片 URL 和 JSON-LD @id 值都由此生成。
• 部署目标。 阅读 vercel.json、netlify.toml、wrangler.toml 或 public/_headers，以确定托管平台。这决定阶段 2 中重定向和标头的语法。
• 网站是否为多语言？ 检查是否有语言子目录（/en/、/nl/、/de/）或构建工具的 i18n 配置。如果有，hreflang 就很重要；如果没有，则跳过。
• <head> 中已有些什么？ 打开一个已构建的 HTML 文件并列出：标题、描述、canonical、robots、Open Graph、Twitter 卡片、JSON-LD、hreflang。如果能参照现有内容，阶段 1 的审查会更快。

只询问无法检测到的信息。

---

阶段 1：审查

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

• 必须 — 发布阻塞项。未通过会导致明显的 SEO 退化。
• 应该 — 标准做法。跳过会降低触达范围。
• 可选 — 面向未来或视情况而定。很有用，但并非所有网站的基本要求。

除非用户要求全面处理，否则小型个人网站可跳过可选检查。

1. 头部元数据（/10）

• 必须 — 每个页面都有 <title> 和 <meta name="description">。
• 必须 — 设置 <link rel="canonical">，剔除跟踪参数，并根据生产环境源站生成。
• 必须 — 当页面设置为 noindex 时省略 canonical（遵循 Google 的建议）。
• 必须 — <title> 长度为 30–65 个字符，<meta name="description"> 长度为 70–200 个字符（SERP 截断范围；与 metadata-check 的默认值相同）。
• 应该 — <meta name="robots"> 包含 max-snippet:-1、max-image-preview:large、max-video-preview:-1。
• 应该 — 每个页面都包含 Open Graph（og:title、og:description、og:image、og:url、og:type、og:site_name）。
• 应该 — 当 Twitter Card 标签（twitter:card）与 Open Graph 重复时省略（Twitter 会自动回退）。
• 应该 — 多语言网站设置 hreflang 替代链接。单语言网站可跳过。
• 应该 — 每个页面仅有一个 <meta name="robots"> 和一个 og:image（旧版工具有时会生成重复项）。

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

• 必须 — 每个重要页面至少包含一个 <script type="application/ld+json"> 块。
• 应该 — 使用关联的 @graph，而非扁平的 Article 对象——通过 @id 引用关联实体，使 BlogPosting 能指向其 Person 作者和 WebPage 父级。
• 应该 — 在相关页面中包含 WebSite、Blog / WebPage、Person / Organization、BlogPosting / Article、BreadcrumbList、ImageObject。
• 应该 — 包含信任信号：publishingPrinciples、copyrightHolder、copyrightYear、knowsAbout、SearchAction。
• 必须 — 通过 Rich Results Test 和 ClassySchema 验证。

3. 内容质量（/10）

• 必须 — 每个页面都有独一无二的 <title> 和 <meta name="description">（全站不重复元数据）。
• 必须 — 每个页面恰好有一个 <h1>。
• 应该 — 使用 metadata-check（第 2.5 阶段）审核 <title> 和 <meta name="description">，检查前置关键词、具体性和 SERP 适配度。
• 应该 — 对单篇长文使用 readability-check 审核正文内容（不要批量审核）。
• 应该 — 每个 <img> 都有 alt 属性（装饰性图片可使用 alt="" / role="presentation"）。
• 应该 — 内部链接使用根相对路径（/foo/），而非绝对路径（https://...）——可适应域名变更和预览环境。

4. Open Graph 图片（/10）

• 必须 — 每个页面都有 OG 图片。
• 必须 — 图片尺寸为 1200×675（Google Discover 的宽度至少为 1200px，宽高比为 16:9）。
• 应该 — 使用 JPEG（社交平台对 OG 图片中的 WebP / AVIF 支持不稳定）。
• 应该 — 在构建时生成（使用 satori-cli、sharp、ImageMagick、Vercel OG、Bannerbear），而非逐页手动上传——避免图片不一致。
• 应该 — 根据 slug 确定性地生成 URL（例如 /og/<slug>.jpg），以便新增页面时自动获得图片。
• 应该 — 正文内容中的每个 <img> 都有 alt 属性（或 alt="" / role="presentation"）。通过 html-proofer 或类似工具在 CI 中验证。

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

• 必须 — /sitemap.xml（若使用拆分站点地图，则为 /sitemap_index.xml）可访问且为有效 XML，每个 URL 均返回 200。
• 必须 — 网站根目录下存在 robots.txt，并且其中引用了站点地图。
• 必须 — 存在 RSS 源，通过 <link rel="alternate" type="application/rss+xml"> 声明，且包含完整文章内容（而非截断的摘要）。
• 应该 — 如果网站有多种内容类型，则按栏目拆分（sitemap-posts.xml、sitemap-pages.xml），以便在 GSC 中更轻松地排查索引问题。
• 应该 — <lastmod> 应从 git 提交时间戳（最准确）、构建时间戳（可接受）或 frontmatter 日期（最后手段）填充。CI 检出的文件系统 mtime 不准确——它表示检出日期，而不是内容日期。
• 应该 — 集成 IndexNow。在网站根目录提供静态 /<key>.txt 路由作为验证密钥，并添加构建或部署钩子，将新 URL POST 到 https://api.indexnow.org/IndexNow。仅在生产主机上提交（例如 CF_PAGES_BRANCH=main、VERCEL_ENV=production、CONTEXT=production）——无条件提交会在本地构建时向端点发送请求，包含生产主机尚未提供的 URL，导致密钥被标记为无效（403），并被迫轮换密钥。

6. Agent 发现（/10）

• 应当 — 提供 schema 端点（/schema/<type>.json），按内容类型公开全站的 JSON-LD。将静态 JSON 文件提交到仓库，或在构建时重新生成。
• 应当 — 提供 schema 映射文件（/schemamap.xml），列出每个 schema 端点，并在 robots.txt 中添加 Schemamap: 指令。
• 应当 — 在网站根目录提供 llms.txt，列出供大模型使用的页面（标题 + 描述）。这是一个静态文本文件，每页一行。
• 应当 — 提供 Markdown 替代 URL（/blog/post/ 旁的 /blog/post.md），以 YAML frontmatter 提供简洁的 Markdown，让 AI Agent 无需解析 HTML 即可使用内容。可以提交 .md 同级文件，也可以使用 Cloudflare Transform Rule + Vary: Accept 进行内容协商（CF Pages 会移除自定义的 Vary 标头，因此只能使用 Transform Rule 的 URL 重写功能——配置方法见 AGENTS.md）。
• 应当 — 按照 RFC 9727，在 /.well-known/api-catalog 提供 API 目录，格式为 application/linkset+json（RFC 9264）。列出 schema 端点、schema 映射文件、RSS 订阅源以及任何网站专属 API。使用静态 JSON 文件。
• 应当 — 在 robots.txt 中添加 Content Signals 指令（Content-Signal: ai-train=yes, search=yes, ai-input=yes，或采用你偏好的政策）。只需一行，属于 IETF 草案，成本低。
• 应当 — 在 /* 上设置指向发现文件（sitemap、llms.txt、api-catalog、schemamap）的 Link 标头。Agent 可通过响应标头找到这些文件，无需解析 HTML。需根据主机进行配置（Cloudflare Pages / Netlify 使用 _headers，Vercel 使用 vercel.json，其他平台使用相应的服务器配置）。
• 可选 — 在 /.well-known/mcp/server-card.json 提供 MCP 服务卡片，和／或在 /.well-known/agent-card.json 提供 A2A Agent 卡片。仅当网站提供 MCP 服务或 A2A Agent 时才适用。
• 可选 — 添加指向对话端点的 <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 数组，用于列出示例提示词。使用静态 JSON 文件。
• 可选 — OKF（Open Knowledge Format）包：由一组类型化 Markdown 概念文件组成的树结构（每页一个文件，路径与规范 URL 对应），打包为单个 .tar.gz，中间穿插索引文件。提供和发现内容并非 OKF 的目标——这正是 ARD 目录条目发挥作用的地方。目前为 v0.9 草案，可选。目前尚无注册的媒体类型，因此临时使用 application/okf-bundle+gzip（已在 knowledge-catalog#111 和 ard-spec#27 中跟踪）；请注明这是临时值，之后可能会更改。最好根据网站其他内容所使用的同一来源生成，而不是手动维护副本。

7. 性能（/10）

• 必须 — 哈希资源应通过 Cache-Control: public, max-age=31536000, immutable（或等效设置）提供，确保只下载一次。
• 应该 — 通过 <link rel="preload" as="font" crossorigin> 以 woff2 格式预加载主要网页字体。
• 应该 — No-Vary-Search 响应标头应从缓存键中剔除 UTM 参数（这样 /?utm_source=x 和 / 共用一个缓存条目）。
• 应该 — 首次绘制时不应有阻塞渲染的 JavaScript（非关键脚本使用 defer 或 async）。
• 应该 — 图片应使用现代格式（页面内容使用 WebP / AVIF；OG 卡片仅使用 JPEG），并对首屏以下的图片设置 loading="lazy"。
• 应该 — Lighthouse / PageSpeed Core Web Vitals 指标均为绿色：LCP < 2.5s，INP < 200ms，CLS < 0.1。

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

• 必须 — 为所有曾经存在且已迁移的 URL 维护 _redirects / vercel.json / 服务器配置。
• 必须 — 永久迁移使用 301，而非 302。
• 必须 — 404.html（或等效页面）应返回 404 状态，而非 200。使用 curl -I 对一个故意输错的 URL 进行验证。
• 应该 — 在 404 页面提供模糊匹配建议（“您是否想找……”），帮助纠正 URL 拼写错误。静态实现：预先构建有效 slug 的 JSON 索引，并在客户端进行模糊匹配。

9. CI 验证（/10）

• 必须 — 在 CI 中加入失效链接检查器。每次推送涉及内容更改时，运行 linkinator 或 lychee。同时检查内部和外部链接：内部链接检查可发现构建回归，外部链接检查可发现链接失效。每周安排一次仅检查外部链接的任务。
• 应该 — 使用 html-proofer 或 W3C Validator 验证 HTML，以发现会影响爬虫的格式错误标记。
• 应该 — 每次推送时运行 Lighthouse CI，并设置分数阈值（例如 SEO ≥ 95，Performance ≥ 80）。
• 应该 — 在 CI 中通过 Schema.org JSON-LD validator 验证 JSON-LD（没有官方 CLI；可通过 Node 脚本将内容 POST 到 API）。
• 应该 — 在 CI 中验证标题和描述长度：编写一个小脚本遍历构建后的 HTML，提取 <title> 和 <meta name="description">，并标记超出 SERP 截断范围的内容（标题 30–65，描述 70–200）。

---

阶段 2：改进

根据审计结果，编写具体代码。覆盖内容前务必先询问。阅读 AGENTS.md 获取详细操作指南。

根据阶段 0 的发现选择方案。 如果网站使用已知构建工具（Hugo、Jekyll、11ty、Gatsby、Next.js），则在源代码层面（模板、配置、frontmatter）应用更改。对于手工编写或抓取的 HTML，则对构建后的输出进行后处理。AGENTS.md 中的操作指南是输出格式指南——展示最终应生成的 HTML——并按工具说明如何接入。

AGENTS.md 章节：Head 元数据（规范代码块）、JSON-LD 图谱、OG 图片生成（构建脚本选项）、sitemap.xml 和 robots.txt、IndexNow、llms.txt、Markdown 替代版本、API 目录、Content Signals、Link 标头、性能标头、按主机配置重定向、CI 工作流。

---

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

对技能生成或修改的每个短字符串调用 metadata-check 技能：页面标题、meta 描述、schema description 字段、FAQ 答案，以及你编写的任何 frontmatter excerpt 值。该技能会检查前置关键信息、具体性、填充内容、主动语态、标题与描述重复、难懂词汇、是否符合 SERP 截断范围（标题 30–65，描述 70–200），以及每个字段是否只表达一个意思。直接应用修正。跳过技术字符串（URL、schema @id 值、枚举值）。

如果项目包含博客或文档板块，请在后续事项中说明可使用 readability-check 技能审查单篇文章的多段落文本质量，但不要自行审查整个内容库。

---

阶段 3：验证

• 构建网站（如果正在迭代，则重新构建）。检查并呈现所有构建警告。
• 抽查构建后的 HTML：任意一个页面的 <head> 都应简洁，canonical 正确，并包含已关联的 JSON-LD 图谱。
• 使用 Rich Results Test 和 ClassySchema 检查首页。
• 确认 /sitemap.xml 存在、返回状态码 200，且引用了正确的 URL。
• 确认 /robots.txt 引用了站点地图，并包含 Content Signals。
• 如果已接入 IndexNow，请确认密钥验证路由 /<key>.txt 返回该密钥。
• 运行本地失效链接检查（linkinator http://localhost:8080 --recurse）。
• 提醒用户完成无法自动化的任务：
  • 在 Google Search Console 和 Bing Webmaster Tools 中注册网站。
  • 在两者中提交站点地图。
  • 生成 IndexNow 密钥，并提交 .txt 验证文件。
  • 安装 Plausible 或其他注重隐私的分析工具。

---

输出格式

## Static SEO audit: [site name]

### Score
| Category                              | Score |
| ------------------------------------- | ----: |
| 1. Head metadata                      |  x/10 |
| 2. Structured data / JSON-LD          |  x/10 |
| 3. Content quality                    |  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. CI validation                      |  x/10 |
| **Total**                             | xx/90 |

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

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

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

---

核心原则

• 审查输出，从源头修复。 该技能会检查构建后的 HTML，但会建议修改生成 HTML 的相应层级（Hugo 模板、Jekyll 布局、11ty include、后处理脚本）。不要建议无法在下一次构建后保留的修复方式。
• 静态 = 主机可移植。 每种方案都应适用于任何静态主机。语法不同时（_redirects 与 vercel.json），两种形式都要提供。
• 关注主题，而非关键词短语。 审查内容时，应关注主题覆盖度和可读性，而非关键词密度。
• Agent 发现如今很重要。 Schema 端点、Schema 映射、llms.txt、API 目录、Markdown 备选格式、MCP / A2A 卡片——爬虫已不再是唯一的使用者。
• Astro 项目优先使用 astro-seo。 该技能通过 @jdevalk/astro-seo-graph 减少了手写样板代码。static-seo 适用于其他所有情况。