文档站 SEO 修复：当版本/翻译/预发页面抢占索引…

对文档站做页面级与技术型 SEO（可索引性、canonical、hreflang、重定向、生成器标题/描述模板、内链），产出按优先级排序、约定通过阈值的修复清单。

适用场景

解决思路

1. 先做访谈（一次只问一题，能多选就多选，跳过用户已说的）。第 1-4 题是门槛题，不做会审计到无关页面或给出平台无法发布的 canonical 姿态：① docs URL 是什么，是否也在平台域名（`*.readthedocs.io`、`*.github.io`、`*.pages.dev`）或第二域名解析；② 用哪个生成器和托管平台，能否改配置并部署；③ 是否分版本，哪些版本发布、哪个是当前、哪些仍被支持；④ 是否翻译，哪些 locale，是否有未审校的机器翻译。
2. 若用户无法改生成器配置或无法部署（第 2 题），直接停下说明：本技能几乎所有修复都是模板或配置改动，逐页 workaround 是更差、仍要别人去发版的交付物。
3. 从 sitemap 构建抓取集（sitemap 与现实的差距本身就是发现）。命令：`python3 scripts/docs-seo-crawl.py https://docs.example.com/sitemap.xml --out pages.csv --summary`；首次大站先抽样 `--limit 300 --delay 0.5 --out sample.csv`；有 URL 列表时 `--urls urls.txt --format json --out pages.json --summary`。
4. 脚本跟进一层 sitemap index，抓取每页并记录：status、title、meta description、canonical；robots 指令（meta 标签与 HTTP header）；第一个 `h1`、粗略词数；出站与入站内部链接数。`--summary` 把问题计数打到 stderr：不可达 URL、`noindex` 页、缺失与重复 title、缺失 canonical、跨站 canonical、薄页面、死胡同、孤儿页。在非自有站点上 `--delay` 不低于默认值，大参考树首轮用 `--limit`。
5. 无可脚本化环境时改为手工抽样：站点入口、每栏目 10 页、参考树 20 页（本技能自定配额，按每小时覆盖率而非统计意义选取），并在报告中声明是抽样。
6. 脚本之外还要检查：`robots.txt`；sitemap 文件本身；以及禁用 JavaScript 抓一个页面。
7. 同时检查 sitemap 的形状，不只内容：sitemaps.org 协议单文件上限 50,000 URL 与 50MB 未压缩，sitemap index 上限 50,000 个 sitemap 且同样受字节上限约束。生成的参考树 × 版本 × 语言是唯一会触及该数字的 docs 场景，生成器输出单个扁平文件会静默越界而不拆成 index。
8. 按 crawl → index → render → signals 顺序先清阻塞性缺陷，依次检查：① `robots.txt` 阻挡了同时带 `noindex` 的路径（经典自相矛盾——被阻挡页面的 `noindex` 永不被读取）；② sitemap 中列了非 200 URL；③ 本应排名的页面被 `noindex`（常从主题默认值或跨栏目复制的 front-matter 继承）；④ 预览、预发、每分支 host 响应时未带 `X-Robots-Tag: noindex`；⑤ 正文、canonical 或导航链接只在 JavaScript 运行后才出现；⑥ `robots.txt` 阻挡了 CSS 或 JS；⑦ 按 agent 的爬虫规则挡得比用户意图更多（含 docs 团队从未选择的 bot 管理默认）。
9. 第 ①-⑥ 项都是阻塞性缺陷：置于修复清单顶部，并覆盖审计其余部分产生的任何分数。第 ⑦ 项是策略决定而非缺陷：搜索发现、用户主动抓取、模型训练是三个独立开关各有成本；一刀切“挡掉 AI bot”通常会把 docs 从公司希望出现的助手答案中移除。该阻挡也可能来自 CDN 或 bot 管理默认而不在 `robots.txt` 里。到此为止，只讨论访问层——发布什么给助手、如何赢得引用不属于本技能。
10. 处理版本与翻译姿态（通用 SEO 审计会跳过、却决定当前版本还是三年前版本赢得查询的一步）。先比较声明姿态（canonical 标签怎么说）与实际姿态（Google 索引哪个 URL），二者经常不一致。
11. 从三种姿态中选一个（下表按性价比而非生成器易用度排序）：① stable-canonical——`/en/stable/…` 与 `/en/v2.3/…`，所有版本 canonical 到 `stable` 别名；平台自带时一小时可上线（Read the Docs 暴露 `READTHEDOCS_CANONICAL_URL`），需手工造别名时约一周；回滚只需改一个 canonical 目标，因为没有任何 URL 移动；当前版本赢得查询，且每个受支持版本仍有活 URL。② latest-only——`/docs/…` 在线，`/v1/…` 归档并 `noindex`；成本近零（归档加一条指令），回滚就是删掉它；当前版本直接赢得查询，但旧版本用户找不到自己那页。③ per-version indexable——每版本一个自 canonical 页加版本切换器；是常态工作，每次发版都成倍放大索引面、sitemap 和链接网，回滚需要对所有已索引版本做逐页重定向表；旧版本读者能落到自己版本的页面。
12. 排序结论：效率 stable-canonical > latest-only > per-version indexable；价值 stable-canonical > per-version indexable > latest-only（只要旧版本仍受支持）；成本 per-version indexable > stable-canonical > latest-only。可逆性不单列，因为其排序与成本完全一致——最难建的姿态也最难拆。默认推荐 stable-canonical 并明说是推荐；只有当前版本被支持且截止期只剩数周时才降到 latest-only；当受支持的 LTS 版本有真实流量、或有支持承诺要求服务每个版本自己的页面时，手动提升 per-version indexable。
13. 从用户约束中删掉被排除的姿态，而不是把它排到最后，并点名删了哪个：无法生成或重定向 `stable` 别名的团队没有 stable-canonical 选项；只发布一个版本的团队根本没有姿态决定，说明后跳过。再对照已知情况重排：平台自带某姿态特性、docs 团队自己掌控 CDN、或已有多年外链的 per-version URL 集合都会改变答案——默认排序是默认，不是定律。
14. 对齐其余信号：① 让 sitemap、canonical 标签和内部链接都指向同一目标（信号冲突正是 Google 自选 canonical 的原因）；② 每个 locale 给自 canonical 加完整 `hreflang` 集合（把翻译 canonical 到英文等于把它从搜索里删除）；③ 站点在多个域名可解析时选定一个主域名，其余 canonical 或重定向到它；④ 退役版本按页选择重定向目标，而不是整棵树送到 docs 首页。写任何 canonical 规则前先让用户确认姿态。
15. `hreflang` 遵循 Google 本地化版本文档的硬性要求（违反按缺陷报告，不是建议）：① 每个语言版本既列出自己、也列出所有其他版本，并包含 `x-default` 处理无匹配情况；② 返回链接必须双向——X 指向 Y 而 Y 不指回，注解可能被整体忽略；③ 值是 ISO 639-1 语言，可选后接 ISO 3166-1 Alpha 2 区域，只给区域是无效的；④ HTML 标签、HTTP header、sitemap 条目是等效交付方式，Google 不偏好。仍在运维上优先用 sitemap：locale × version 树会把几百个标签塞进每个 `<head>`；新 locale 上线时重生成整张网——加了 `/ja/` 却不重生成 `/fr/` 的 alternates，会让 `/ja/` 缺少来自 `/fr/` 的返回链接。
16. 在模板层修页面信号（docs 站的 title、description、标题结构是生成的，改一次模板覆盖所有页面；逐页改写其次，只用于带流量的页面）：① 改写 title 模板，把被搜索词放前、品牌放后，本技能默认形状为 `{page} | {product} {section}`，可适配但保持顺序；② 为 quickstart、头部 how-to 与最高流量参考条目写 description，其余走回退而不是生成填充；③ 每页一个描述性主标题、层级向下不跳级，不因存在第二个有效 `h1` 判页面失败，只判断层级是否无歧义；④ 保持 heading `id` 锚点在构建间稳定，让长参考页能赢得锚点级结果并支持产品深链；⑤ 跳过 `HowTo` 与 `FAQPage` 结构化数据——Google 已撤回这两种富结果（`HowTo` 2023 年 8 月，`FAQPage` 到 2026 年 5 月完全撤回），`BreadcrumbList` 仍渲染且 docs 有真实层级可表达。
17. 把字符数当 lint 而非门槛。Google 声明 `<title>` 无长度限制：标题链接按设备宽度截断，50-60 字符规则只检查重要部分是否存活。docs 站真正付出代价的失败是被改写：当 Google 发现 title 有问题（docs 站通常是样板或面包屑形状）时，可能用 heading、锚文本、`og:title` 及其他页面文本自建标题链接——要修的是模板为何无用，缩短它什么也改变不了。
18. 修内部链接：先修孤儿页（抓取脚本会列出），再修死胡同，然后从高流量页（quickstart 与头部 how-to 是有权威可传递的页面）添加语境化正文链接。跨模式链接收益最大：tutorial → reference 指向它用到的符号；reference → how-to 指向它服务的任务；troubleshooting → 故障发生的指南。用描述性锚文本，绝不用 “here” 或 “read more”。同一轮检查关键词自蚕食：博客教程与 docs how-to 指向同一任务会分割展示且都赢不了，确定哪个界面拥有该查询，让输家链向赢家。
19. 页面体验：docs 站通常很快，然后因一次添加而退化——客户端搜索组件、嵌入的 API explorer、未优化的一组图表。检查 docs 路径而非域名平均的 Core Web Vitals。各指标及格线来自 Google；要求多少比例的 docs URL 达标是与用户共设的目标（本技能基线 90%）。环境能跑页面速度审计时，对三种页面类型跑——docs 首页、一篇长指南、一个参考页——并迭代到各自通过；不能跑时用 Search Console 的字段数据并声明缺少实验室数据。
20. 交付按优先级排序的修复清单，不是发现堆。报告按序覆盖：结论段；覆盖率声明（列明无法核实的内容）；阻塞性缺陷；版本与翻译姿态；页面信号；内部链接；排序后的修复清单与约定阈值。每行修复写明改什么、在哪个文件或系统、谁负责——无 owner 列的缺陷清单下次审计会原样回来。按（受影响页数 × 严重度）÷ 工作量排序（本技能自定公式，非标准），阻塞性缺陷无论如何置顶；并在报告中明说这是比率而非严重度列表。该比率会挤压触及页数少却要一周的修复（客户端渲染外壳的服务端渲染、以及受众说明里的企业页面集合），当这些页正是业务付钱的页面时手动提升它们。
21. 在修复开始前与用户约定通过阈值作为终点，并把两类数字分开——只有一类可协商。搜索引擎强制的是缺陷不是阈值：`robots.txt` 禁止的页面其 `noindex` 或 canonical 永远不被读取；无返回链接的 `hreflang` 集合可能被整体忽略；超过 50,000 URL 或 50MB 未压缩的 sitemap 文件不合规。这些放进阻塞性缺陷段，不容讨论。
22. 阈值表（本技能自定基线，非行业标准）：≥95% canonical docs URL 被索引；零页面被 Google 选了不同 canonical；sitemap 中零非 200 URL；100% 唯一 title；零孤儿页；零被索引的预览或退役版本 URL；≥90% docs URL 通过 Core Web Vitals。说明它们是默认值后按站调整：20 页的 docs 站应达 100% 索引，20,000 页的参考树不会。
23. 把排名结果报告为待定，因为确实如此：本次会话能验证配置与一致性，但重新索引、重新排名、重写摘要按搜索引擎的时间表发生。编造排名因素权重或预测流量增长会让技术正确的审计失去可信度。修复落地后重跑抓取并 diff 两份 summary——该 diff 才是工作落地的证明，原始发现清单不是。
24. 按受众区分承重页面：面向自服务采纳者的 docs 落在 quickstart、how-to 与错误页；面向公司采购评估的 docs 落在 limits、security、compliance、self-hosting 与 migration 页——通常是站点上最薄、最少链接、最少被索引的页面，因为没人把它们当文档。产品有企业动线时必须显式检查第二组；按流量排序的页面清单永远不会浮现它。
25. 用失败模式表自查：已阻挡又 noindex；canonical 轮盘（sitemap、canonical 标签、导航指向三个不同版本）；canonical 指向内容不同的当前页（应改为重定向到最近等价页）；翻译被抹除（`/fr/` canonical 到 `/en/`）；单向 hreflang；sitemap 超上限；把 title 裁到 60 字符；一刀切 AI-bot 阻挡；构建戳 lastmod（每页 `lastmod` 等于上次部署，应从源文件 commit 日期推导或干脆去掉）；预览页进索引；逐页打地鼠（手写 400 个 title 而不是改一次模板）；前言式摘要（每页开头都是“Acme 是一个……”，应在首屏回答查询）；弃用的 schema（HowTo/FAQPage）；参考树整体 noindex（应保持可索引，按资源分而非按字段分）；退役版本 URL 全部重定向到 docs 首页；只有分数没有阈值（“docs SEO 健康度 78/100”）；用第三方估算查询量而非 Search Console 或明确标注“未核实”。

适用边界 · 注意事项

• 需要做关键词研究、决定该瞄准哪些查询时——改用 samber/developer-relations-skills@developer-keyword-research。
• 需要的是跨整个 docs 集的页面覆盖与放置审计、错误与排错页内容、面向编码 agent 的机器可解析表面，或全部 devrel 表面的跟踪计划时——分别路由到 developer-docs-structure-audit / developer-troubleshooting-docs / coding-agent-docs-optimization / devrel-analytics。
• 用户无法修改生成器配置或无法部署时——本技能几乎所有修复都是模板或配置改动，逐页 workaround 清单是更差、且仍需别人去发版的交付物。