VuePress 与 VitePress：该选哪一个？

对于几乎所有新建的 Vue 文档站点，请选择 VitePress。

如果你最近还在维护一个 VuePress 1 的站点，你应该很清楚那种感觉：保存一个 Markdown 文件，然后趁着 webpack 重新构建的时间去干点别的事。这个等待间隙，基本上就是这场对比的核心所在。

VitePress 是 Vue 团队官方推荐的静态站点生成器，VuePress 1 已被弃用，而 VuePress 2 由社区维护，且仍处于候选发布（RC）阶段。只有当你确实需要 VuePress 2 目前仍做得更好的某些能力时才选它，比如定制化的插件/主题 API，或者更便捷的组件替换；如果你需要一等公民级别的文档版本管理，则应转向基于 React 的生成器，例如 Docusaurus。

本文将用真正决定一个文档项目走向的具体差异来论证这个结论：项目活跃度、开发反馈循环速度、定制化的权衡取舍，以及 VitePress 目前确实还做不到的事情。同时，本文也会纠正你在一些旧对比文章中仍能看到的”VitePress 还处于 alpha 阶段”这类过时说法。

VuePress 和 VitePress，哪个在积极维护？

项目活跃度是这个决策中权重最大的单一因素，而它的指向非常明确。VitePress 承接了 VuePress 的思路，在 Vue 3 和 Vite 之上实现同样的”Markdown 转文档”理念。Vue 团队得出结论：无法同时维护两个生成器，于是确定 VitePress 为官方推荐方案，让 VuePress 1 退役，并将 VuePress 2 移交给社区团队。

成熟度的实际情况与旧文章的说法恰好相反。VitePress 才是稳定的那一个：npm 上最新版本仍是 1.6.4，而更新日志显示下一个大版本仍在 alpha 阶段，为 2.0.0-alpha.19。VuePress 核心仓库至今仍将自身状态描述为候选发布版，因此 VuePress 2 从未达到最终稳定版本。此外，Vite、Rollup、Pinia、VueUse、Vitest、D3、UnoCSS、Iconify 以及 Vue.js 官网本身的文档，都由 VitePress 驱动。

开发体验：Vite 对比 webpack

开发反馈循环是 VitePress 拉开差距的地方。VuePress 1 构建在 Vue 2 和 webpack 之上，很快就显得过时；VitePress 运行在 Vue 3 和 Vite 之上。官方文档指出，从保存文件到在屏幕上看到变化的时间不到 100 毫秒，无需页面重载，也无需等待开发服务器启动。这与 webpack 的重新构建完全是两个量级的反馈体验。

产物架构同样重要。在开发阶段，除非你另行指定，开发服务器运行在 5173 端口。在生产环境中，访问者首次落地的页面是预渲染的静态 HTML，加载快且利于索引；随后 VitePress 会将其激活（hydrate）为一个 Vue 单页应用，因此之后的所有导航都在浏览器中完成，正如1.0 发布公告所解释的那样。VitePress 还内置了本地全文搜索（只需一个配置项）以及 Shiki（VS Code 使用的同一款语法高亮器），两者都无需手动接入。

配置与定制化：真正的权衡

这里有一个必须坦诚面对的张力。VitePress 配置更简单，默认主题确实相当出色，但深度定制意味着你要写 Vue。VitePress 出于设计考虑没有自己的插件系统：定制化通过自定义主题和插槽委托给 Vue，通过配置和插件委托给 Vite。VuePress 2 保留了更宽泛、定制化的插件/主题 API，并让在配置中替换组件更为直接——这也是为什么一些已深度定制 VuePress 站点的团队有时会选择留在原地。

这种设计有其实际的粗糙之处。覆盖默认主题 Vue 组件内部的 scoped 样式时，偶尔不得不动用 !important。侧边栏要简单得多，并支持为每个子目录配置独立的侧边栏，但你需要在 themeConfig.sidebar 中手写出来：新增的 Markdown 文件在你修改配置或引入社区插件（如 vitepress-sidebar）之前不会出现。Frontmatter 直接写在 Markdown 中，可读性很好；上一页/下一页链接默认从侧边栏推断，除非你自己设置 prev 和 next——它们可以指向任意页面，无论该页是否在侧边栏中。

VitePress 的侧边栏配置很清晰：

// .vitepress/config.ts
export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        collapsed: true,
        items: [
          { text: 'Introduction', link: '/guide/' },
          { text: 'Getting Started', link: '/guide/getting-started' },
        ],
      },
    ],
  },
}

当你希望每个板块拥有独立的侧边栏时，使用以路径为键的对象形式（sidebar: { '/guide/': [...] }）。这正是 VuePress 处理起来更麻烦的多侧边栏模式。

什么情况下 VitePress 不是合适的选择？

VitePress 的定位是刻意收窄的，有几处短板是实实在在的。它没有一等公民级别的文档版本管理：同时维护 v1/v2/v3 的团队只能保留各自的版本目录并手动配置侧边栏，这也是转而选择 Docusaurus 的主要理由。相较 Docusaurus，它的插件生态较小。它的博客能力较弱：没有内置的标签系统、RSS 订阅或归档页面，因此一个偏营销性质的站点用它来做，投入产出不划算。而且一旦你的需求超出 Markdown 和默认主题，它就要求你会 Vue。

除非你确实需要一等公民级别的版本管理或庞大的插件库（那是 Docusaurus 的领域），或者你的技术栈是 React（那么 Fumadocs、Nextra 或 Docusaurus 更合适），否则请选择 VitePress。

从 VuePress 迁移，以及最终结论

搭建一个新的 VitePress 站点只需四条命令：npm add -D vitepress，然后用 npx vitepress init 运行初始化向导，npm run docs:dev 启动本地服务器，npm run docs:build 将静态产物输出到 .vitepress/dist。当前官方文档中的安装命令默认指向 2.0-alpha 分支（vitepress@next），并要求 Node.js 22 及以上版本，因此使用普通的 npm add -D vitepress 才能装到稳定的 1.x。

从 VuePress 迁移并非即插即用。你的 Markdown、frontmatter 和通用 Markdown 扩展可以顺利沿用；但配置结构、主题和布局必须重做，任何定制的 VuePress 插件都需要找到 VitePress 的对应方案。使用默认主题的站点迁移起来最为轻松。

决策准则如下：新建 Vue 文档站点，选 VitePress，不必回头张望。如果你在使用 VuePress 默认主题的站点上，迁移到 VitePress。如果你需要一等公民级别的版本管理或深厚的插件库，那就认真评估 Docusaurus。如果你的技术栈是 React，直接从基于 React 的生成器起步。安装 VitePress，运行 npx vitepress init，在你读完配置参考文档之前，一个可用的文档站点就已经跑起来了。

常见问题

VuePress 被弃用了吗？

VuePress 1 已被弃用并处于维护模式，而 VuePress 2 被移交给社区团队，至今仍是候选发布版，从未发布最终稳定版。Vue 团队认为并行维护两个生成器不可持续，现在推荐 VitePress 作为其主要的静态站点生成器。在 npm 上，VuePress core 的 'latest' 标签仍解析到 1.x 分支，进一步印证了 2.0 从未走出 RC 阶段。

VitePress 能根据我的目录结构自动生成侧边栏吗？

不能。VitePress 默认不会自动生成侧边栏。新增的 Markdown 文件在你手动编辑配置文件中的侧边栏，或安装诸如 vitepress-sidebar 这类社区插件之前，都不会出现。VitePress 确实支持以路径为键的多侧边栏，因此你可以为每个子目录定义独立的侧边栏，但这个映射关系是显式声明的，而非从目录树推导得出。

VitePress 是否像 Docusaurus 那样支持文档版本管理？

不支持。VitePress 没有内置的一等公民级版本管理功能。需要同时维护多个文档版本的团队只能保留各自的版本目录，并手动配置侧边栏。如果带下拉切换的版本化文档是硬性需求，Docusaurus 是更强的选择，因为一等公民级的版本管理是它的核心特性之一。这也是选择基于 React 的生成器而非 VitePress 的最常见原因。

为什么 VitePress 的深度定制需要编写 Vue 组件？

VitePress 出于设计考虑没有自己的插件系统。它没有定制化的插件 API，而是把定制化通过自定义主题和插槽委托给 Vue，通过配置和插件生态委托给 Vite。这让核心保持精简，但也意味着覆盖默认主题的外观或行为需要编写 Vue 组件，偶尔还要用 !important 强制覆盖 scoped 样式，而不是简单切换几个配置项。