VitePress 与 Docusaurus：文档站框架选型指南
README 写到三千字，新人还是不知道从哪看起；文档散在 Notion、飞书、Wiki，搜一条要开三个 Tab。要正经搭一个对外文档站时，VitePress 和 Docusaurus 几乎总会出现在候选名单里——都是 Markdown 驱动的静态站点生成器（SSG），产物是可部署的 HTML，不是 WordPress 那类 CMS。
快速结论：团队主栈 Vue、文档量不大、追求轻量极速 → 优先 VitePress。需要多语言、多版本文档并存、文档门户一体化 → 优先 Docusaurus。没有「谁更强」，只有是否匹配你的规模与维护方式。
两条路线，各是什么来头
VitePress：Vue 生态的轻量文档站
- 维护方：Vue 团队；底层 Vue 3 + Vite
- 设计取向：默认主题够用、配置项少、本地预览极快
- 常见案例：Vue、Vite、Vitest 官方文档
- 适合心智：「先把文档站跑起来，别在工具上耗太久」
Docusaurus：面向门户的 React 文档平台
- 维护方：Meta；底层 React，构建链为 Webpack / Rspack
- 设计取向：文档、博客、更新日志、i18n、版本切换等能力开箱集成
- 常见案例：React、Jest、Babel 等大型开源项目文档站
- 适合心智：「文档是要长期运营的产品，而不只是几页说明」
选型前先回答三个问题
- 团队更熟哪套前端栈？ VitePress 定制走 Vue，Docusaurus 走 React，组件不能混用。单人维护时，「顺手的栈」比 star 数重要。
- 文档规模与结构有多复杂？ 几十篇中文文档，和几百页 + 多语言 + v1/v2 并存，对框架的要求完全不同。
- 站点要不要「门户感」？ 仅文档即可，还是要博客、Changelog、分类标签、编辑此页链 GitHub 等一整套——这决定你更偏向哪边。
分块对比：开发、内容、运营
开发与构建
| 项目 | VitePress | Docusaurus |
|---|---|---|
| 上手成本 | 低，.vitepress/config.js 即可起步 |
中等，需理解 preset、plugin、swizzle 等概念 |
| 本地预览 | Vite HMR，改动几乎即时可见 | 可用，大项目冷启动与热更新相对慢 |
| CI 构建 | 中小站通常较快 | 页面、语言一多，build 时间需单独评估 |
| 定制方式 | Vue 组件 + 主题配置 | React 组件 swizzle，灵活但学习曲线陡 |
写作与内容组织
| 项目 | VitePress | Docusaurus |
|---|---|---|
| 内容格式 | Markdown 为主，可嵌 Vue 组件 | Markdown + 原生 MDX（嵌 React 组件） |
| 导航配置 | 侧边栏、路由在 config 中维护，直观 | docusaurus.config.js + sidebars.js，模块更细 |
| 文档运营细节 | 基础能力齐全，深度功能靠插件或自建 | 分类、标签、上下篇、文档卡片等更成熟 |
| 博客 | 有，偏简约 | 官方 Blog 插件完善 |
多语言、版本与搜索
| 项目 | VitePress | Docusaurus |
|---|---|---|
| 多语言 i18n | 需自行配置或借助社区方案 | 内置，一等公民 |
| 文档版本 | 依赖插件（如 vitepress-plugin-version） | 内置 versioning，v1 / v2 切换成熟 |
| 站内搜索 | 本地搜索 / Algolia 插件 | 本地搜索 / Algolia 集成 |
| 插件生态 | 精而够用 | 丰富，社区活跃 |
按场景对号入座
- 内部 Wiki、产品说明、开源库文档（中文为主、几十到百篇量级）
选 VitePress。配置轻、预览快，Vue 团队几乎零额外学习成本。 - 对外开发者门户，要 en/zh 切换、旧版 API 文档长期保留
选 Docusaurus。i18n 与版本管理不用从零拼，省下来的集成时间通常值回学习成本。 - 文档 + 博客 + 更新日志要放在同一个站里
选 Docusaurus。官方插件组合更完整；VitePress 也能做，但要自己搭更多模块。 - 只有一个人维护，且主栈是 Vue
选 VitePress，日常改文档、改主题的摩擦最小。 - 先快速上线，以后再考虑扩容
可先用 VitePress 落地；规模上来再评估迁 Docusaurus——Markdown 正文大多能复用，配置与主题需重写，别指望一键迁移。
部署与 SEO：两者差别不大
构建产物都是静态 HTML / JS / CSS，部署目标相同：Nginx、Vercel、Netlify、GitHub Pages、对象存储 + CDN 均可。SEO 方面，SSG 本身对爬虫友好；最终效果取决于 title / description、sitemap、内链结构和内容质量，而不是框架名字。搜索上，小团队或内网文档用本地搜索往往足够；对外大型门户可考虑 Algolia DocSearch（开源项目可申请免费额度）。
常见疑问
- Vue 和 React 能不能混用？
- 不建议。选型时跟团队主栈对齐，长期维护成本最低。
- 从 Hexo、VuePress 1.x 迁过来麻烦吗？
- Markdown 正文大多能搬，front matter 可能要微调；路由、主题、插件需按新框架重做。选型阶段知道「内容可复用、工程要重来」即可。
- SEO 是不是 Docusaurus 更好？
- 两者都是 SSG，搜索引擎友好度在同一水平。页面结构、加载速度、内容更新频率更关键。
- 性能数据看哪里？
- 别死磕旧帖或 star 数。以各版本官方文档和你在目标规模下的实测为准。
总结
VitePress 和 Docusaurus 不必二选一绑死——对外门户用 Docusaurus、内部 Vue 项目文档用 VitePress，分开建反而清楚。搭站之前，先想清楚文档谁写、谁审、更新频率如何；框架再合适，没人维护也白搭。
真正合适的框架，是你愿意持续往里填内容、团队也肯跟着维护的那一套。