文档即代码与托管平台：2026 年的权衡
“文档即代码”——文档存储在 Git 中，通过拉取请求进行审阅，并通过 CI 部署——是以工程为主导的公司的主流模式。“托管平台”——登录、配置并发布——是以设计为主导的公司和独立开发者公司的主流模式。两者都行得通，也都会以不同的方式失败。
这就是 2026 年需要诚实面对的权衡。
简而言之#
| 文档即代码 | 托管平台 | |
|---|---|---|
| 文档存放位置 | Git | 平台的数据库或 Git |
| 编辑 | 在 IDE 中使用 Markdown，通过 PR 审查 | Web 编辑器或 Markdown |
| 部署 | CI/CD 流水线 | 推送后无需操心 |
| 托管 | 由你托管 | 由他们托管 |
| 维护 | 你的工程工时 | 供应商的工时 |
| AI 功能 | 自行构建或集成 | 内置 |
| 成本形式 | 工程工时 | 订阅费用 |
| 最适合 | 工程驱动、开源软件、深度定制 | 初创公司、独立开发者、“立即发布” |
Docsbook 很有意思，因为它兼具两者的特点：源文件存放在 Git（你的代码仓库）中，其余部分全部由平台管理。
“文档即代码”何时胜出#
文档即代码仍然是正确模式的三个理由：
1. 工程已经存在于 Git 中#
如果你的文档撰写者是工程师，那么使用 Git 编写文档的认知负担为零。拉取请求、代码审查、分支预览——所有现有的工程工作流都能自然延伸到文档中。
2. 版本控制与代码发布保持一致#
随代码变更一起发布的文档变更应包含在同一个 PR 中。审阅者可以同时看到 API 变更和文档变更。CI 会对两者进行测试。
3. 需要大量定制#
如果你的文档需要 React 组件、自定义 Markdown 扩展，或需要一个根据 OpenAPI 规范生成页面的构建流水线，那么使用 Docusaurus、Nextra 或 VitePress 的文档即代码模式是正确的选择。
“托管平台”胜出时#
托管方案胜出的三个原因：
1. 文档撰写者不是工程师#
产品营销人员、支持团队成员和客户成功负责人经常需要更新文档。要求他们向 Git 仓库提交 Markdown PR 会造成阻碍，使文档无法及时更新。网页编辑器更快捷。
2. 需要 AI 功能，而你的团队不会构建它们#
一个提供 AI 聊天、AI 翻译、MCP、llms.txt 和分析功能的托管平台，会将这些功能分别作为开关提供，而不是作为项目。 如果由你来构建，每一项都是真正的项目：检索、评估闭环、带有按区域设置路由的翻译管道、事件存储。对于大多数团队而言，仅为文档构建这些功能都没有充分的理由。
3. 部署所有权是开销，而非价值#
自托管文档网站上的重复性工作确实存在，但没有固定安排：大版本迁移、依赖项和 Node 版本漂移、无人负责的构建失败，以及需要重新审批或重新托管的搜索功能。这些工作都不会交付读者能够看到的任何内容。
应根据你自己的代码仓库而不是平均值来估算成本：统计过去四个季度中对文档基础设施进行的、但未更改任何内容的提交次数。这个数字就是托管平台能够消除的工作量。
混合模式：Docsbook#
Docsbook 与这两类都不完全匹配，因此比较特殊。
- 事实来源是你的 GitHub 仓库（代码即文档属性）
- 托管、AI、搜索、翻译、分析和 MCP 均由平台管理（托管平台属性）
- 没有 CI/CD 流水线、没有
docusaurus.config.js、没有 swizzle（托管平台属性） - PR 和审查的工作方式相同（代码即文档属性）
- 不会被供应商锁定——离开时，你的文件仍保留在 GitHub 中（代码即文档属性）
这种模式很重要，因为纯代码即文档模式（部署负担）和纯托管模式（供应商锁定）的失败模式会相互抵消。
成本计算#
让我们比较一下一个典型的 5 名工程师初创公司的 24 个月总拥有成本。
纯文档即代码（Vercel 上的 Docusaurus）#
| 项目 | 24 个月成本 |
|---|---|
| 在付费层级上托管 | 一笔你不会注意到的周期性账单 |
| 初始设置 | 一次性的工程工时 |
| 大版本迁移 | 工程工时，两年内大约需要两次 |
| 季度维护 | 周期性的、未安排的工程工时 |
| 构建 AI 聊天 | 数周工程工作，外加持续负责检索质量 |
| 运行 AI 聊天 | 向量存储、嵌入和模型调用，每月产生 |
| 搜索（Algolia DocSearch 或自行托管） | 获批准则免费，否则需要订阅或投入更多工时 |
| 翻译流程 | 通常会被跳过，因为它属于项目，而不是一个单独的项目项 |
托管方#
| 项目 | 24个月成本 |
|---|---|
| 订阅或按量计费 | 供应商的数字——在其自己的定价页面上查看 |
| 初始设置 | 不到一小时 |
| 维护 | 无 |
如何实际进行这项比较#
请使用您自己的数字填写两张表，而不是我们的数字。我们特意没有在此公布任何金额，因为唯一诚实的数字只能是您的数字：您的托管层级、工程师的综合成本、您的流量。
填写完成后，有两点值得注意。首先，工程工时占据了自托管栏的大部分，而且这些往往是没有人纳入预算的项目。其次，自托管一侧的翻译一行几乎总是空白——这并不是因为翻译毫无价值，而是因为它作为一个项目从未达到立项标准。这意味着，除非您明确说明，否则这种比较并不是真正的同类比较。
（Docsbook 之前曾销售一次性终身 PRO 方案；该方案现已不再提供，现有终身方案购买者仍保留原有条款。）
当成本计算结果逆转#
文档即代码更便宜的三种情况：
- 工程师工时是免费的 — 你有一名专门负责文档平台的工程师；无论如何都需要支付其薪资
- 拥有社区贡献者的 OSS 项目 — 社区 PR 分担了维护工作量
- 在文档中使用自定义 React 组件 — 托管平台无法实现这一点
对于这些情况，Docusaurus 或 VitePress 是正确的选择。除此之外，成本计算结果倾向于托管方案。
供应商锁定：如何评估#
向任何托管平台提出以下三个问题：
- 我现在可以将内容导出为纯 Markdown 吗？ 如果可以，锁定程度就较低。
- 如果我迁移，URL 能保留吗？ 大多数平台允许保留 URL；有些则不允许。
- 如果我取消服务，我的自定义域名会怎样？ 应该可以取回。
Docsbook 在这三点上表现良好：文件位于你的 GitHub 仓库中（导出 = git clone），URL 与文件路径匹配（保留 = 重定向），自定义域名是由你控制的 DNS 记录。
GitBook 在第一点上表现较差（内容存储在其数据库中），在其他方面表现良好。Mintlify 在三点上都表现良好。
决策规则#
- 工程主导、开源软件、重度定制 → 文档即代码（Docusaurus、VitePress、Nextra）
- 独立开发者、初创公司、“立即发布” → 托管平台（Docsbook、Mintlify）
- 拥有 30 名以上编辑者的企业 → 企业级托管（GitBook）
- 想要混合方案 → Docsbook（Git 源代码库，其他全部由平台托管）
相关阅读#
Docsbook 是混合型方案：源文件保留在 Git 中，同时由 AI、SEO、翻译和 MCP 统一管理。定价按 AI 使用量计费，而不是按套餐级别销售——当前价格请查看 docsbook.io/pricing。