# 文档站与开发者产品的 GEO 最佳实践

> AI 工具会引用能以纯文本取到、且能对上正确版本的文档。放行搜索爬虫和用户触发的抓取，每页提供服务端渲染的 HTML 和对应的 Markdown，每个版本只保留一个规范网址。llms.txt 成本低可以做，但它不是排名手段。

- URL: https://geo.casa/zh-cn/best-practices/developer-docs/
- 指南 · 官方文档已说明
- 审核于: 2026-10-28

这篇写给运营文档站、API 参考或开发者产品的人。开发者现在常常先问 ChatGPT、Claude、Perplexity 或编程助手，再去翻文档。目标是让这些回答引用你当前、正确的页面。大部分工作是一次性的工程改造，几天可以完成，之后靠发布流程里的习惯维持。

## 一句话路线

1. 让 AI 搜索爬虫和用户触发的抓取能访问文档。
2. 每页正文都放进服务端 HTML。
3. 为每页提供干净的 Markdown 版本。
4. 每个文档版本只保留一个规范网址，并让「最新版」一目了然。
5. 代码示例和参考页要经得起被单独摘出来引用。
6. 用带日期、可链接的变更日志发布改动，站点地图如实反映更新。
7. 平台能低成本生成 llms.txt 就加上，但别指望它影响排名。

## 1. 放行该放行的爬虫

文档站常常和产品共用一套机器人防护。好页面从不出现在 AI 回答里，最常见的原因就是这个。有两类机器人要关心：提前索引页面的搜索爬虫，和用户提问时临时抓取页面的用户触发型抓取。

> **官方文档已说明:**
> OpenAI：「退出 OAI-SearchBot 的网站不会出现在 ChatGPT 搜索回答中，但仍可能以导航链接的形式出现。」
>
> 参考来源: [OpenAI: Overview of OpenAI crawlers](https://developers.openai.com/api/docs/bots)

> **官方文档已说明:**
> Anthropic 区分 ClaudeBot（训练）、Claude-User（用户请求的抓取）和 Claude-SearchBot（搜索索引）。屏蔽 Claude-User 或 Claude-SearchBot 可能降低在 Claude 中的可见度。
>
> 参考来源: [Anthropic: Does Anthropic crawl data from the web, and how can site owners block the crawler?](https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler)

> **官方文档已说明:**
> PerplexityBot 用于在 Perplexity 搜索结果中展示并链接网站。Perplexity-User 在用户提问时抓取页面，因为是用户发起的请求，它通常不遵守 robots.txt 规则。
>
> 参考来源: [Perplexity: Perplexity crawlers](https://docs.perplexity.ai/docs/resources/perplexity-crawlers)

- 放行搜索类标识：Googlebot、Bingbot、OAI-SearchBot、Claude-SearchBot、PerplexityBot。
- 训练类爬虫（GPTBot、ClaudeBot、Google-Extended）单独决定。屏蔽它们不会让你从搜索中消失。
- 除了 robots.txt，还要查 CDN 或 WAF。各标识的细节见 [为 AI 爬虫配置 robots.txt](https://geo.casa/zh-cn/crawling-indexing/robots-txt-ai-crawlers/)，完整检查见 [技术/SEO 负责人的 GEO 最佳实践](https://geo.casa/zh-cn/best-practices/technical-lead/)。

## 2. 正文放进 HTML

很多文档框架在浏览器里渲染导航和正文。不执行 JavaScript 的爬虫看到的就是一个空壳。

> **官方文档已说明:**
> Google 推荐服务端渲染或预渲染，因为「并非所有机器人都能运行 JavaScript」。
>
> 参考来源: [Google Search Central: Understand JavaScript SEO basics](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics)

> **实践观察:**
> Vercel 和 MERJ 于 2024 年 12 月发布的测试发现，他们考察的主要 AI 爬虫都不渲染 JavaScript，包括 OpenAI、Anthropic 和 Perplexity 的爬虫。使用 Googlebot 基础设施的 Gemini 会渲染。
>
> 参考来源: [Vercel & MERJ: The rise of the AI crawler (17 Dec 2024)](https://vercel.com/blog/the-rise-of-the-ai-crawler)

用 `curl -s <网址>` 检查，在输出里搜正文中的一句话和代码示例中的一行。标签页、折叠面板和「复制」组件的内容要留在 HTML 里，用 CSS 隐藏，而不是点击后再加载。更多见 [JavaScript 渲染与 AI 爬虫](https://geo.casa/zh-cn/implementation/javascript-rendering-ai-crawlers/) 和 [Next.js、Vue 等前端渲染站点：让 AI 爬虫读到正文](https://geo.casa/zh-cn/best-practices/javascript-sites/)。

> curl 看不到的代码示例，大多数 AI 爬虫也看不到。

## 3. 每页提供 Markdown 版本

Markdown 去掉了导航、脚本和版式，助手拿到的只有内容。一些文档平台已经能自动生成。

> **官方文档已说明:**
> Mintlify 会在文档项目根目录自动托管 `llms.txt` 和 `llms-full.txt`。llms.txt 中的页面链接带 .md 扩展名，AI 工具可以直接抓取每页的 Markdown 版本。
>
> 参考来源: [Mintlify: llms.txt](https://www.mintlify.com/docs/ai/llmstxt)

> **官方文档已说明:**
> GitBook 提供 `/llms.txt`，列出每个已发布页面的 Markdown 版本；`/llms-full.txt` 则把全部文档放在一个文件里。在任一已发布页面网址后加 `.md`，就能得到该页的 Markdown。
>
> 参考来源: [GitBook: LLM-ready docs](https://gitbook.com/docs/publishing-documentation/llm-ready-docs)

自建站点可以照搬这个模式：`页面网址.md` 返回源 Markdown，标题和代码块保持完整。它必须与 HTML 页面一致。和 HTML 不同步的 Markdown，就是一份过期的第二版文档。「复制为 Markdown」或「在 ChatGPT/Claude 中打开」按钮，也应使用同一个文件。

## 4. 每个版本一个规范网址

版本化文档会产生近似重复的页面：`/v2/auth`、`/v3/auth`、`/latest/auth`。助手引用错了版本，用户就会复制已废弃的代码。

> **官方文档已说明:**
> Google 按强弱给规范化信号排序。重定向和 `rel="canonical"` 是强信号，列入站点地图是弱信号。多种信号叠加，首选网址被选中的机会更大。
>
> 参考来源: [Google Search Central: How to specify a canonical URL with rel="canonical" and other methods](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)

- 当前版本选一个稳定网址（例如 `/docs/auth`），`/latest/` 别名用 `rel="canonical"` 指向它。
- 旧版本有用户需要就保留，但在页面标题和第一行写明：「第 2 版（已废弃）。当前版本：v3。」
- 站点地图和 llms.txt 只列当前版本的页面。
- 版本号和「最后更新」日期写在可见正文里，不只放在下拉菜单中。

背景见 [规范网址（canonical）信号](https://geo.casa/zh-cn/crawling-indexing/canonical-signals/)。

## 5. 页面要经得起被摘引

AI 回答会摘走一段文字或一个代码块，其余的丢掉。本节是本站基于文档被引用方式给出的编辑建议，不是平台文档的规定。

- 每个代码示例都要完整：导入语句、包名、安装命令和版本。
- 每页开头写明前置条件和适用版本，不要只写在入门页。
- 一个概念只用一个名字。SDK 方法叫 `createClient`，别处就别叫「初始化调用」。
- 每条报错信息单独一个标题或表格行，写出完整报错原文。开发者会把报错直接粘贴给助手。
- 每个 H1 下面用一句话说明这页是干什么的。

通用写作建议见 [写给内容编辑：写出容易被 AI 摘引的文章](https://geo.casa/zh-cn/best-practices/content-editor/) 和 [说法核查：内容必须为 AI 搜索切块和改写](https://geo.casa/zh-cn/content-structured-data/chunking-content/)。

> 文档是一块一块被引用的。每个代码示例都应该能单独跑通。

## 6. 改动标日期，站点地图说实话

API 改了以后，旧答案会一直留在助手里，直到新页面被重新抓取。每次发布一个网址、带日期的变更日志，让爬虫和用户都有一个地方了解改了什么。

> **官方文档已说明:**
> Google 忽略 `<priority>` 和 `<changefreq>`。只有当 `<lastmod>` 始终准确且可验证（例如与页面最后修改时间对得上）时，Google 才会使用它。
>
> 参考来源: [Google Search Central: Build and submit a sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)

- 每条发布说明有独立锚点或页面，写明日期和受影响的版本。
- 变更日志条目链接到更新后的参考页，参考页也链回来。
- 只在内容变化时更新 `<lastmod>`，不要每次构建都改。见 [XML 站点地图（Sitemap）](https://geo.casa/zh-cn/crawling-indexing/xml-sitemaps/) 和 [XML Sitemap 与 IndexNow 对比](https://geo.casa/zh-cn/tools-protocols/sitemaps-vs-indexnow/)。
- 废弃某个功能时，在旧页面上写明，而不是直接删掉。

## 7. llms.txt：有用，但不是排名手段

llms.txt 是一份提议中的、给语言模型看的索引文件。对文档站来说，它是个合理的便利，尤其是编程工具或用户会主动加载它。但它不是在 AI 搜索中获得排名的办法。

> **官方文档已说明:**
> `/llms.txt` 是一项提议（llmstxt.org，2024 年），在网站根目录放一个 Markdown 文件，简述网站并链接关键页面，可附 Markdown 版本。目的是帮助语言模型在推理时使用网站。
>
> 参考来源: [llmstxt.org: The /llms.txt file](https://llmstxt.org/)

> **官方文档已说明:**
> Google 搜索不使用 llms.txt 文件。为其他服务维护这类文件，「既不会损害也不会提升网站在 Google 搜索中的可见度或排名，因为 Google 搜索会忽略它们」。
>
> 参考来源: [Google Search Central: Optimizing your website for generative AI features on Google Search](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)

> **实践观察:**
> DATA17 在 2026 年的研究中检查了一个品类 163 个品牌域名的 llms.txt。被某 AI 助手提及的品牌部署 llms.txt 的比例（17%）反而低于从未被提及的品牌（27%）。被提及的品牌只有 18 个，作者的解读是没有可测出的正面效果。
>
> 参考来源: DATA17 AI Research Lab · 解数智能: 你的公司还在 AI 的答案里吗：企业 GEO 行动指南 · 2026 (未公开报告，没有公开链接，读者无法自行核对)

平台自动生成的，开着就好。手工维护的，要和站点地图从同一数据源生成，避免过期。完整证据见 [说法核查：llms.txt 能提升 AI 搜索可见度](https://geo.casa/zh-cn/tools-protocols/llms-txt/)。

> llms.txt 是给主动要它的开发者准备的，别指望它带来引用。

## 不要做的事

- **不要在文档 CDN 上一刀切屏蔽所有机器人。** 搜索类和用户抓取类爬虫与训练类是分开的（[为 AI 爬虫配置 robots.txt](https://geo.casa/zh-cn/crawling-indexing/robots-txt-ai-crawlers/)）。
- **不要给 AI 机器人看不同的内容。** HTML、Markdown 和 llms.txt 从同一个源生成。Google 认为主要为操纵 AI 回答而另做内容有风险（[规模化内容滥用（Scaled content abuse）](https://geo.casa/zh-cn/content-structured-data/scaled-content-abuse/)）。
- **不要让 `/latest/` 和 `/vN/` 互相竞争。** 选定规范网址（第 4 节）。
- **不要只用图片或交互沙盒放示例。** 页面上要有文字版。
- **不要把 llms.txt 当成 GEO 项目本身。** 它只是很小的一项（[说法核查：llms.txt 能提升 AI 搜索可见度](https://geo.casa/zh-cn/tools-protocols/llms-txt/)）。

## 怎么判断有没有效果

- **日志：** 统计 OAI-SearchBot、Claude-SearchBot、PerplexityBot 和用户抓取类代理对文档网址（含 `.md` 网址）的已验证访问（[在服务器日志中验证 AI 爬虫流量](https://geo.casa/zh-cn/implementation/verify-ai-crawlers/)）。
- **Bing AI Performance 报告：** 看 Copilot 和 Bing AI 引用了哪些文档页（[Bing AI 表现报告（AI Performance）](https://geo.casa/zh-cn/measurement/bing-ai-performance/)）。

> **官方文档已说明:**
> 微软：「AI Performance 不衡量排名、权威、表现或重要性，只显示哪些内容被引用。」
>
> 参考来源: [Microsoft Bing: AI Performance report (Bing Webmaster Tools help)](https://www.bing.com/webmasters/help/ai-performance-9f8e7d6c)

- **固定问题集：** 保留 20–30 个真实的开发者问题（如「X SDK 怎么分页」），每月跑一次，看回答是否引用你的文档、用的是否当前版本（[用提示词抽样测量 AI 可见度](https://geo.casa/zh-cn/measurement/ai-visibility-measurement/)）。
- **工单：** 给「用户照着过时 AI 回答操作」的工单打标签。这个数字下降，才是真正要的结果。

## 证据一览

| 建议 | 证据 |
|---|---|
| 放行搜索和用户抓取类爬虫 | 官方（OpenAI、Anthropic、Perplexity） |
| 服务端渲染 HTML | 官方（Google）+ 实践观察（Vercel/MERJ，2024） |
| 每页提供 Markdown 版本 | 官方平台功能（Mintlify、GitBook）；对引用的影响未经检验 |
| 每个版本一个规范网址 | 官方（Google 规范化信号） |
| 自足的代码示例和报错页 | 推测（本站编辑建议） |
| 准确的 `lastmod` 和带日期的变更日志 | `lastmod` 为官方（Google 站点地图）；变更日志结构为本站建议 |
| llms.txt | 官方：Google 搜索忽略；实践观察：一项研究中无可测效果 |

## 参考来源

- [OpenAI: Overview of OpenAI crawlers](https://developers.openai.com/api/docs/bots)
- [Anthropic: Does Anthropic crawl data from the web, and how can site owners block the crawler?](https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler)
- [Perplexity: Perplexity crawlers](https://docs.perplexity.ai/docs/resources/perplexity-crawlers)
- [Google Search Central: Understand JavaScript SEO basics](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics)
- [Vercel & MERJ: The rise of the AI crawler (17 Dec 2024)](https://vercel.com/blog/the-rise-of-the-ai-crawler)
- [Google Search Central: How to specify a canonical URL with rel="canonical" and other methods](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)
- [llmstxt.org: The /llms.txt file](https://llmstxt.org/)
- [Google Search Central: Optimizing your website for generative AI features on Google Search](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
- DATA17 AI Research Lab · 解数智能: 你的公司还在 AI 的答案里吗：企业 GEO 行动指南 · 2026 (未公开报告，没有公开链接，读者无法自行核对)
- [Mintlify: llms.txt](https://www.mintlify.com/docs/ai/llmstxt)
- [GitBook: LLM-ready docs](https://gitbook.com/docs/publishing-documentation/llm-ready-docs)
- [Google Search Central: Build and submit a sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)
- [Microsoft Bing: AI Performance report (Bing Webmaster Tools help)](https://www.bing.com/webmasters/help/ai-performance-9f8e7d6c)