产品的第二官网：vibe 项目的文档站搭建实战

划界：本篇讲的是给人看的文档站怎么搭建，与站内三篇明确分工：vibe-project-help-center-knowledge-base-guide（帮助中心知识库）讲的是"帮助中心的内容运营"，本篇讲的是"文档站的技术搭建"——运营 vs 基建；docs-written-for-ai-agents（给 AI 写文档）讲的是"给 AI 看的文档怎么写"，本篇讲的是"给人看的文档站怎么做"——读者对象相反；vibe-project-changelog-release-communication-guide（Changelog）讲的是"版本发布的喜报沟通"，本篇第 4 节讲的是"文档随版本走"——发布沟通 vs 文档版本化。

API 产品、开源项目、进阶 SaaS，迟早都需要一个文档站。AI 能一晚上糊出一个"看起来像文档"的页面：左侧目录、右侧正文、暗色切换全都有。然后你发现：新用户进来不知道先看哪篇；v2.0 发布了，文档还写着 v1.5 的参数；搜索框搜"鉴权"返回 0 结果——因为搜索只匹配了标题；API 改了个字段，文档没人记得改。文档站是产品的第二官网：官网负责"让人心动"，文档站负责"让人用起来"。AI 能糊页面，但做不出"能用的文档站"——信息架构、版本化、搜索、与代码同步更新，四件事缺一不可。本文给一人团队一条实战路线：要不要独立建站、四家工具怎么选、信息架构怎么摆、版本怎么跟、搜索怎么做、文档怎么跟代码同步、反馈怎么做、上线前查什么。

一、要不要独立文档站：三者的读者与分工

先别急着选型。很多 vibe 项目同时有三样东西：README、帮助中心、文档站——或者该有但不知道该建哪个。决策看读者：

• README：读者是"路过的开发者"，场景是 GitHub 仓库页。只回答三个问题：这是什么、30 秒跑起来、去哪看更多。一页纸，超过 200 行就该拆了。
• 帮助中心：读者是"遇到问题的用户"，场景是"我密码忘了怎么办"。内容运营导向：FAQ、故障排查、账单问题——写给非技术用户看的，归客服和运营。
• 文档站：读者是"要集成/深度使用你产品的开发者"，场景是"我要调你的 API / 配你的 SDK"。技术基建导向：快速开始、概念、指南、API 参考——归工程。

决策表：

• 纯工具/内容型产品，无 API、无复杂配置 → README + 帮助中心就够了，别建文档站。
• 有 API 或 SDK，或配置项超过 20 个 → 建独立文档站。帮助中心继续服务终端用户，两者读者不同，不要硬合并。
• 开源项目 → README 做门面，文档站做纵深。Star 增长后"issue 里反复被问的三个问题"就是文档站第一批内容。

一句话：当你在 README 里开始写"详细配置见…"却不知道指向哪里时，就是该建文档站的时候。

二、选型：四家工具的一人团队对照

候选就四家：Fumadocs、Starlight、Docusaurus、Mintlify。截至 2026-10-16 亲核的公开资料，先说能写进正文的事实，再说决策：

• Fumadocs：MIT 开源、免费自托管，Next.js 生态（App Router），内置全文搜索（Orama）、OpenAPI 渲染，组件可按"内容→核心→UI"三层拆着用。已验证的公开记录显示它在 2026 年增长极快（有资料称周下载 15 万量级、v0 的文档站即用它搭建——该量级表述来自第三方 2026 年 4 月资料，仅供参考）。适合：团队已经在用 Next.js 的项目。
• Starlight：Astro 官方的文档主题，MIT 开源、免费自托管，内置 Pagefind 搜索与 i18n，暗色模式与无障碍开箱即用。适合：想要"装上就有完整文档站"、不折腾配置的团队；Astro 底子让它对非 React 组件（Vue/Svelte）也友好。
• Docusaurus：Meta 出品，MIT 开源、免费自托管，生态最大（插件、主题、中文社区资料最多），版本化文档是一等公民。适合：需要版本化 + 大量自定义 + 长期维护的项目；React 技术栈无缝。
• Mintlify：托管型 SaaS（不用自己搭服务器），MDX 写文档、GitHub 自动部署，OpenAPI 生成 API 参考是强项。有免费 hobby 档；付费计划的具体价格各第三方资料说法不一（2026 年资料中有 150 美元/月、300 美元/月等不同口径），以官网为准。适合：想"今天就上线"、不愿运维的团队；代价是定制上限和长期费用。

中文支持的实话：四家都有 i18n（多语言）能力，但"支持 i18n"不等于"开箱即中文"——中文站都要按各自的 i18n 文档配置路由、翻译界面文案、处理搜索分词（中文搜索建议用支持 CJK 的方案，见第 5 节）。选型时不要被"支持中文"的营销话术迷惑，去看它 i18n 文档里有没有中文站的完整示例。

一人团队拍板规则：

• 已经在用 Next.js → Fumadocs（技术栈统一，维护成本最低）。
• 想要最快有个像样的站、不想调配置 → Starlight。
• API 产品、要长期做版本化、要深度定制 → Docusaurus。
• 今天就要上线、完全不想运维 → Mintlify（先算好付费档的长期成本）。

选定后不要摇摆：文档站的迁移成本不在工具，在几十篇已写好的内容格式。

三、信息架构：四块内容，两条读者路径

文档站信息架构的经典错误是"按功能模块平铺"：把 40 篇文档按后端模块名一字排开。新用户进来看到"认证服务、计费服务、通知服务"——他只想知道"我 5 分钟能跑起来吗"，你的目录却在给他上系统架构课。

文档站首页截图（Starlight 搭建）：导航、搜索框与内容分区

经过验证的四块划分（见上图）：

• 快速开始：5 分钟跑通第一个例子。这是文档站的首页 C 位，也是转化率最高的页面。标准：复制三段命令，能看到输出。写不出来"5 分钟版本"，说明你的上手路径本身有问题，先修产品再写文档。
• 概念：心智模型。"Project、Key、Quota 三者的关系"这类文章。读者是"我想理解它怎么 work"的人，篇幅短、图多。
• 指南：场景化"怎么做"。"如何实现按量计费""如何对接 Webhook"。按用户任务组织，不按你的代码模块组织。
• API 参考：每个接口的参数表。从 OpenAPI/TSDoc 自动生成（第 6 节），人工只写"注意"和"示例"。

两条读者路径：首页 60 秒自测分流——"我是新手"进快速开始，"我来查东西"直达搜索/API 参考。验收标准：新手路径 3 次点击内必须跑通第一个例子，否则信息架构就是失败的，自己走一遍就知道。

四、版本化文档：发版时文档怎么跟版本走

"文档落后于代码"是文档站的慢性病，病因永远是"发版流程里没有文档这一环"。两种版本化策略：

• 快照式（推荐一人团队）：每次发版时把当前文档打一个快照（/docs/v2.2、/docs/v2.3），默认展示最新版，旧版只读。Docusaurus 的版本化就是这个思路。成本：每次发版多一道"打快照"的工序——把它写进发版 checklist，和改 CHANGELOG 同一级。
• 分支式：文档跟代码同一仓库、同一分支走，v2.3 分支的文档天然就是 v2.3 的。适合文档即代码的团队，但要求发版流程规范，否则分支一多就乱。

预防"文档落后"的三道机制：

• 发版 checklist 里有文档项。"API 参数变了→API 参考更新了→快速开始里的示例还能跑通吗"三连问，答完才能发版。
• 文档里的代码示例进 CI。快速开始里的三段命令，CI 里真的跑一遍。跑挂了发版就红——这是"文档不会烂"的唯一硬保证。
• 每页标注"最后验证版本"。页脚小字"本文验证于 v2.3.1"，读者一眼知道这篇还靠不靠谱，也倒逼你定期复查。

五、搜索实战：DocSearch 申请门槛与本地搜索

文档站没有好搜索等于没有。两条路线：

路线 A：Algolia DocSearch（免费，但有门槛）

截至 2026-10-16 亲核 DocSearch 官方文档（docsearch.algolia.com）：免费计划面向公开的技术文档与技术博客；申请走 Algolia 后台的自动化验证，获批后 7 天内必须验证域名所有权，自动判不定的走人工复核（1–2 个工作日）。注意它的拒绝条件：未上线、内容非技术向会被拒。vibe 项目的文档站只要"已上线 + 是技术文档"一般都能过，但上线第一天就去申请可能因"内容单薄"被判不通过——先攒出 20 篇以上再申请，通过率高得多。

路线 B：本地搜索（0 门槛，立刻有）

Starlight 内置 Pagefind、Fumadocs 内置 Orama、Docusaurus 有 @easyops-cn/docusaurus-search-local 纯客户端方案。本地搜索的优点是零申请、离线可用、部署预览环境也能搜；缺点是索引打进包里，文档上千篇时包体积要留意。一人团队的务实路线：先用内置本地搜索上线，文档破 50 篇后再申请 DocSearch——两条路线不互斥，很多站是本地搜索打底、DocSearch 接管后的渐进增强。

搜索无结果的兜底

无论哪条路线，无结果页都要做三件事：① 给出"你是不是想找"的近似推荐（本地搜索的 typo 容忍、DocSearch 的同义词）；② 放"去 GitHub 提 issue 问"的入口（把搜索失败变成内容需求，衔接第 7 节）；③ 记录无结果搜索词——这是文档选题的最佳来源，每月看一次。

六、与代码同步：API 参考从 OpenAPI/TSDoc 自动生成

API 参考手写是死路：接口一改，文档必忘。正确姿势是文档从代码生成，人工只写机器写不出的部分：

• REST API：后端导出 OpenAPI spec（NestJS/FastAPI 等主流框架都有官方插件），文档站用 spec 渲染参数表、请求示例、响应 schema。Mintlify 和 Fumadocs 对 OpenAPI 的渲染都是强项（第 2 节）。
• SDK/函数库：用 TSDoc/JSDoc 写注释，TypeDoc 等工具抽成 API 页面。规则：注释写"为什么这么设计 + 一个能跑的例子"，参数类型让工具从类型定义里抽——人只写机器推不出的信息。
• 机器可读层：复用站内 agent-friendly-api-design 的思路——llms.txt / 结构化的 API 描述既服务人类读者，也服务来读你文档的 AI Agent。一份 OpenAPI spec，同时喂给文档渲染器和 AI，是一鱼两吃。

流程固化：CI 里加一步"spec 变更检测"——OpenAPI 文件变了而文档站没重新部署，流水线就黄灯。把"文档与代码同步"从"靠自觉"变成"靠流水线"。

七、反馈闭环：把文档变成获客漏斗

每篇文档底部放"这篇文档有帮助吗？👍 / 👎"——别小看这个组件，它是文档站最重要的埋点：

• 👎 点下去展开追问："哪里没讲清楚？（多选：步骤跑不通 / 缺示例 / 过时了 / 太啰嗦）+ 留言框"。选项设计决定你收到的是可行动的反馈还是情绪垃圾。
• "在 GitHub 上提 issue"一键入口：预填标题（含页面路径）和模板，把反馈摩擦降到最低。文档 issue 和代码 issue 打不同标签，方便分流。
• 轻量 RICE 排期：衔接 vibe-project-user-feedback-loop-guide 的方法——按"👎 数 × 影响页面流量"排序，每月修 Top 5。文档优化第一次有了 ROI 公式，不再是"有空再说"。

进阶玩法：把高频 👎 的页面做成"新手任务"——"把这篇文档改到能让新人 5 分钟跑通"，是社区贡献的绝佳切口，也是文档站变成获客漏斗的开始：来提 issue 的人，一半会变成你的用户。

八、上线检查表：10 项

• 1. 60 秒分流可用：新用户 3 次点击内跑通快速开始的第一个例子，真人走一遍。
• 2. SEO 基础：每页独立 title/description、sitemap、canonical。文档站 40% 流量来自搜索，上线第一天就要有。
• 3. 搜索可用：搜三个核心词（产品名 + "鉴权" + "计费"）都有结果；无结果页有推荐 + 提 issue 入口。
• 4. 深色模式：代码块在深色下可读（对比度）、切换无闪烁（避免 FOUC，先读 localStorage 再渲染）。
• 5. 移动端代码块横滑：真机检查：代码块横向滚动、不撑破布局；行号不遮挡代码。
• 6. 404 兜底：自定义 404 页，带搜索框 + "可能想找"的链接，而不是服务器默认页。旧外链很多是指向文档的，404 体验直接影响口碑。
• 7. 版本切换器：旧版本快照可访问、默认最新版、搜索引擎不收录旧版（noindex）——别让用户搜到 v1.5 的文档来调 v2.3 的接口。
• 8. 反馈组件：每页底部 👍/👎 + GitHub issue 入口，👎 数据能进你的看板。
• 9. 示例代码可跑：快速开始的三段命令在 CI 里真的跑过，发版 checklist 含文档项。
• 10. 性能预算：文档站是静态站，没有理由慢。Lighthouse 性能 90+，首屏 < 2s（4G）。超了先查是不是把整套 UI 库打进了每个页面。

文档站上线后，每月做一次"文档体检"：👎 Top 5 页面、无结果搜索词 Top 10、跳出率最高的 3 篇——修完再看下月数据。文档站和产品一样，是靠迭代变好的。第二官网的KPI 只有一个：新用户从"看到文档"到"跑通第一个例子"的转化率，盯住它，其他都是手段。