Appearance
VitePress 专篇：基于 Vite 的文档站点生成器
最后更新：2026-08-19
本主题要回答的问题
- VitePress 是什么？它和"框架/构建工具"是什么关系？
- 从 VuePress 到 VitePress 演进了什么？为什么 Vue 官方最终选择了它？
- 一个 Markdown 文档站，从源码到线上 HTML 的完整构建链路是什么？
- 与 Docsify、Docusaurus、Astro 等方案比，VitePress 的取舍在哪？
一、定位：一句话说清 VitePress
VitePress = Vite + Vue 3 + markdown-it 拼装出来的"文档站 SSG"。它属于SSG 家族：构建期把 Markdown 编译成静态 HTML，部署后无需服务器渲染，天然拥有首屏快、SEO 好的静态站特性。
| 组成 | 承担什么 |
|---|---|
| Vite | 开发服务器（秒启热更）、构建打包、静态资源处理 |
| Vue 3 | 默认主题组件、客户端水合、自定义主题的扩展接口 |
| markdown-it | Markdown 语法解析 + 插件扩展（自定义容器、代码高亮） |
| VitePress 本体 | 约定与集成：config.ts、sidebar、frontmatter、路由映射 |
二、从 VuePress 到 VitePress：为什么"重写"
VuePress 1.x（2018）是 Vue 生态最早的文档站方案，但它的底层是自研的构建管线 + Vue 2，与现代工具链脱节：
| 对比项 | VuePress 1.x | VitePress |
|---|---|---|
| 底层构建 | 自研 + Webpack | Vite（原生 ESM + esbuild） |
| Vue 版本 | Vue 2 | Vue 3 |
| 开发启动 | 慢（全量打包） | 秒级（按需转译） |
| 插件生态 | 自成一派 | 对齐 Vite/Rollup 生态 |
| 维护方 | VuePress 团队 | Vue 官方（VuePress 已归档维护） |
演进本质：VuePress 验证了"文档站需要哪些能力"，VitePress 则把这些能力重新建立在 Vite 之上——开发体验对齐现代前端、构建产物更小更快、主题开发用标准 Vue 3 组件。这也是"前端自我进化"在工具链层面的又一个实例（与构建工具演进呼应）。
三、构建链路：从 Markdown 到线上 HTML
关键机制拆解：
| 环节 | 做什么 | 例子（本站） |
|---|---|---|
| 路由映射 | README.md → 目录首页；foo.md → /foo | /overview、/concepts/ |
| 侧边栏 | _sidebar.md 经脚本转成 themeConfig.sidebar | .vitepress/gen-sidebar.mjs |
| Markdown 扩展 | 自定义容器、PlantUML、源码内联 | 构建期插件渲染 PlantUML 为 PNG |
| frontmatter | 页面级 meta（title/description） | 构建期生成静态 SEO meta |
| 静态生成 | 每个页面在构建期 SSR 出完整 HTML | 294 篇文档 → 294 个 HTML |
| 资产指纹 | 文件名加 hash，缓存友好 | *.js/*.css 自动加指纹 |
四、与同类方案对比
| 方案 | 定位 | 强项 | 短板 |
|---|---|---|---|
| VitePress | Vue 生态文档站 SSG | 快、主题漂亮、Vue 组件化 | 主要面向文档，非通用站点 |
| Docsify | 运行时渲染的单页文档 | 零构建、一个 HTML 全包 | 无预渲染，SEO 差 |
| VuePress 2 | VitePress 的"重"版本 | 插件生态成熟 | 配置重、默认体验不如 VitePress |
| Docusaurus | React 生态文档站 | 文档 + 博客 + 多版本 | 依赖重、启动慢 |
| Astro Starlight | 内容岛架构文档站 | 默认零 JS，性能极致 | 社区较新 |
本站从 Docsify 迁到 VitePress 的动因（实测收益）：Docsify 是运行时渲染——浏览器先下载 Markdown 再渲染，SEO 差、无预渲染、还有大量手写插件胶水（1300 行 index.html 逻辑）。VitePress 是构建期渲染：真实 HTML 落盘，天然解决 SEO、死链可检测、PlantUML 构建期内联成图片，cleanUrls + canonical 统一 URL 形态。
五、本站的 VitePress 落地实践
| 能力 | 实现方式 | 收益 |
|---|---|---|
| PlantUML 图 | 构建期插件：本地 plantuml.jar 常驻进程池渲染 PNG 落盘 public/plantuml/ | 运行时零外部请求、点击可放大 |
| 源码直链 | 构建期把 .cpp 读入内联成代码块（替代 Docsify 的运行时 request 钩子） | 死链转实链，语法高亮 |
| SEO | 每页 canonical + og:url + 静态 meta | 消除重复 URL 稀释权重 |
| 本地搜索 | VitePress 内置 localSearch | 删掉手写搜索插件 |
| 侧边栏 | gen-sidebar.mjs 把 _sidebar.md 转成 sidebar 配置 | 索引仍用 Markdown 维护 |
| 更新显示 | lastUpdated（来自 git 提交时间） | 自动展示文档更新时间 |
六、何时选 VitePress、何时不选
| 场景 | 建议 |
|---|---|
| 项目文档 / 组件库文档 / 个人笔记站 | 选 VitePress（上手快、默认主题够用） |
| 博客 + 文档 + 多版本发布 | 考虑 Docusaurus 或 VitePress 博客插件 |
| 复杂业务应用（登录、后台） | 不选，用 Next.js/Nuxt 这类元框架 |
| 需要极致零 JS 性能 | 对比 Astro |
一句话总结
VitePress 是"前端自我进化"的缩影：它用构建期渲染拿回了静态站的可靠性（SEO、首屏、可检测），又用 Vite 生态拿回了现代开发体验（秒启、HMR、Vue 组件化）——它证明了一个规律：在文档这类"内容构建期已知"的场景里，把渲染从浏览器挪到构建期，是比运行时更优的复杂度归属。