VuePress 以 Markdown 为中心的 Vue 静态站点生成器技术调研

VuePress 是以 Markdown 为中心的 Vue 静态站点生成器，由 Vue 社区维护，适合构建文档、博客、知识库和静态内容站。VuePress 1.x 已 deprecated，VuePress 2.x 目前处于 Release Candidate（RC）阶段，API 和配置仍可能有小的 breaking changes。2026 年，Vue 官方团队已转向 VitePress，VuePress 2 由 VuePress team / 社区继续维护。新项目通常优先评估 VitePress，仅在已有 VuePress 资产、需要其插件/主题生态或需要 Webpack bundler 时选择 VuePress 2。

一、 基本信息

二、 版本历史与 2026 年现状

2026 年核心趋势

1. VuePress 1.x 已 deprecated：不应再新建 VuePress 1 项目。
2. VuePress 2.x 仍为 RC：尚未发布正式稳定版，配置和 API 可能有小的 breaking changes。
3. Vue 官方主推 VitePress：Vue.js team 已转向 VitePress，VuePress 2 由 VuePress team / 社区维护。
4. VuePress 2 适合特定场景：已有 VuePress 资产、需要插件/主题生态、需要 Webpack bundler 的项目。
5. npm 标签容易混淆：npm install vuepress 默认安装 1.x，安装 VuePress 2 必须显式使用 vuepress@next。

三、 技术定位与简介

VuePress 的定位是 Vue 生态的 Markdown 驱动静态站点生成器。它将 Markdown 编译为静态 HTML，并在客户端以 Vue + Vue Router 驱动 SPA 导航。VuePress 最早服务于 Vue.js 及其子项目文档；Vite 出现后，Evan You 创建了 VitePress，而 VuePress v2 由社区继续推进。

VuePress 当前适合：

• 已有 VuePress 资产、需要其插件/主题生态的项目。
• 需要 Webpack bundler 的项目。
• 需要 VuePress 2 的特定插件或主题的项目。

VuePress 不适合：

• 没有 VuePress 资产的新项目（通常优先 VitePress）。
• 需要稳定主版本 API、低升级风险的长期项目（VuePress 2 仍为 RC）。
• 非 Vue 技术栈团队，或更偏 React / Python / Astro 生态的项目。
• 复杂应用型网站、强动态服务端渲染、用户系统或实时交互应用。

四、 快速上手安装说明

1. 使用 VuePress 2（必须显式安装 @next）

# 使用官方脚手架
pnpm create vuepress vuepress-starter
 
# 手动安装
mkdir vuepress-starter
cd vuepress-starter
pnpm init
 
pnpm add -D vuepress@next vue
pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next

2. 标准项目结构

docs/
├── README.md                    # 首页（VuePress 默认首页）
├── guide/
│   └── README.md
├── .vuepress/
│   ├── config.ts                # 站点配置
│   ├── client.ts                # 客户端配置（可选）
│   ├── components/              # 自定义 Vue 组件
│   └── styles/                  # 自定义样式
└── package.json

3. 核心配置示例

// docs/.vuepress/config.ts
import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'
 
export default defineUserConfig({
  title: 'My Docs',
  description: 'VuePress documentation site',
  lang: 'zh-CN',
 
  bundler: viteBundler(),
  theme: defaultTheme({
    navbar: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
    ],
    sidebar: [
      {
        text: '指南',
        children: ['/guide/'],
      },
    ],
  }),
})

4. 常用脚本

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

5. 使用 pnpm 的注意事项

使用 pnpm 时，官方文档提示需要安装 vue peer dependency。

五、 核心特性

1. Markdown 内容驱动

文档、博客、知识库可直接以 Markdown 管理，降低内容维护成本。

2. Vue in Markdown

Markdown 页面可使用 Vue 模板语法和组件，增强文档交互能力。

3. 静态生成

构建阶段为每个路由生成 HTML，适合部署到静态托管平台。

4. SPA 导航

站点初始页面是静态 HTML，后续导航由 Vue Router 驱动。

5. 双 Bundler 支持

VuePress v2 支持 Vite 和 Webpack：

• Vite bundler：推荐，现代开发体验。
• Webpack bundler：适合已有 Webpack 配置或特定兼容需求。

// Vite bundler
import { viteBundler } from '@vuepress/bundler-vite'
 
// Webpack bundler
import { webpackBundler } from '@vuepress/bundler-webpack'
 
export default defineUserConfig({
  bundler: viteBundler(), // 或 webpackBundler()
})

6. 插件系统

提供 Node App / Client App 两侧扩展点：

• Markdown 处理。
• 页面扩展。
• 客户端文件注入。
• alias、define、bundler options 等。

7. 主题系统

• 默认主题可配置。
• 自定义主题。
• 社区主题（Hope Theme、Plume Theme、Reco Theme 等）。

8. Markdown 扩展

基于 markdown-it，可扩展：

• 语法。
• 代码高亮（Shiki / PrismJS）。
• TOC。
• 链接转换。
• 自定义容器。

9. 官方生态插件

VuePress Ecosystem 提供插件分类：

• 搜索（DocSearch、Meilisearch、local search、slimsearch）。
• SEO、PWA、Analytics、Blog、Markdown、AI、Development、Tool。

六、 适用场景

七、 技术亮点

1. Markdown 与 Vue 结合紧密

VuePress 的核心优势是 Markdown 内容可直接使用 Vue 模板语法和组件，适合写可交互文档。

2. 支持 Vite 和 Webpack

VuePress v2 不完全绑定单一 bundler，为需要 Webpack 的项目保留选择空间。

3. 插件 API 覆盖全面

插件 API 覆盖 Markdown 处理、页面扩展、客户端文件注入、alias、define、bundler options 等环节。

4. 官方生态独立维护

VuePress Ecosystem 独立维护插件，插件类别比 VitePress 更偏站点功能组合（SEO、PWA、Blog、Analytics 等）。

5. 架构区分 Node App 与 Client App

这种区分适合插件和主题扩展，但也增加了自定义开发的心智成本。

6. 默认主题覆盖文档站常见需求

默认主题提供导航、侧边栏、多语言、代码高亮、搜索集成等能力。

八、 核心概念与架构

1. 架构分层

digraph VuePress_Architecture {
  rankdir=TB
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  Markdown [label="Markdown 文件 + Frontmatter", fillcolor="#bae6fd"]
  NodeApp [label="Node App"]
  ClientApp [label="Client App"]
  Theme [label="Theme"]
  Plugin [label="Plugin"]
  Bundler [label="Bundler (Vite / Webpack)"]
  Static [label="静态 HTML 输出"]
  Hydrate [label="客户端水合为 Vue SPA"]
 
  Markdown -> NodeApp
  NodeApp -> Theme
  NodeApp -> Plugin
  NodeApp -> Bundler
  Theme -> ClientApp
  Plugin -> ClientApp
  Bundler -> ClientApp
  Bundler -> Static
  Static -> Hydrate
}

2. 核心概念

• Site Source：站点源目录，通常包含 Markdown 内容和 .vuepress/ 配置目录。
• Config：.vuepress/config.ts，定义站点标题、主题、插件、bundler、Markdown 配置。
• Page：每个 Markdown 文件会生成页面和路由。
• Theme：控制布局、导航、侧边栏、页面组件和样式。
• Plugin：扩展 VuePress 构建流程、Markdown、客户端增强、页面数据。
• Bundler：处理 Client App 和临时文件，当前支持 Vite / Webpack。
• Client Config：注册客户端组件、增强 Vue app、接入路由。

3. Node App 与 Client App

• Node App：加载配置、主题、插件，解析 Markdown，生成页面、路由和临时文件。
• Client App：由 bundler 处理，作为普通 Vue 应用运行。

4. Markdown 处理流程

Markdown 文件会被 markdown-it 编译，并作为 Vue 组件模板处理；构建时会访问每个路由并生成 server-rendered HTML。

九、 技术局限与边界

1. VuePress 2 仍是 RC 阶段： 配置和 API 可能出现小范围 breaking changes。

2. npm 默认 latest 指向 1.x： 使用 VuePress 2 必须显式安装 vuepress@next，否则会得到已 deprecated 的 1.x。

3. 与 VitePress 定位分化： Vue.js team 聚焦 VitePress，VuePress 由 VuePress team / 社区维护。新项目通常优先 VitePress。

4. 不适合复杂业务系统： VuePress 更适合内容型静态站，不适合承载复杂业务系统。

5. 插件和主题生态需逐个评估： 尤其是非官方/社区插件，需要检查维护状态和兼容性。

6. 自定义主题开发门槛较高： 自定义主题和插件需要理解 Node App / Client App 边界，否则容易出现 SSR、客户端 API 或 bundler 兼容问题。

7. Vue 3 响应式与 Webpack/Vite 构建差异： 双 bundler 支持虽然灵活，但也可能带来构建行为差异，需要针对性测试。

十、 生态地图

VuePress 生态主要围绕 @vuepress 命名空间和 VuePress Ecosystem 展开：

digraph VuePress_Ecosystem {
  rankdir=TB
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  VuePress [label="VuePress 2", fillcolor="#bae6fd"]
 
  VuePress -> Core [label="vuepress"]
  VuePress -> ViteBundler [label="@vuepress/bundler-vite"]
  VuePress -> WebpackBundler [label="@vuepress/bundler-webpack"]
  VuePress -> DefaultTheme [label="@vuepress/theme-default"]
  VuePress -> Ecosystem [label="VuePress Ecosystem"]
  VuePress -> Marketplace [label="VuePress Marketplace"]
 
  Ecosystem -> Search [label="DocSearch / Meilisearch / local search"]
  Ecosystem -> SEO [label="SEO Plugin"]
  Ecosystem -> PWA [label="PWA Plugin"]
  Ecosystem -> Analytics [label="Analytics Plugin"]
  Ecosystem -> Blog [label="Blog Plugin"]
  Ecosystem -> AI [label="AI Plugin"]
}

十一、 生态集成

十二、 开发与工程化

1. 推荐目录结构

docs/
  README.md
  guide/
    README.md
  .vuepress/
    config.ts
    client.ts
    components/
    styles/

2. 工程建议

• 新项目优先使用 TypeScript 配置文件：.vuepress/config.ts。
• 明确锁定 VuePress 2 RC 版本，避免无意识升级。
• 每次升级 RC 版本阅读 changelog。
• vuepress@next、bundler、theme 的版本组合要保持一致。
• CI 中至少执行依赖安装、vuepress build docs、链接检查或静态产物检查。
• 大型文档站建议加入搜索索引更新、死链检查、sitemap 检查、多语言路径检查和图片体积检查。
• 插件和主题自定义较多时，应记录插件版本、配置意图和升级风险。

3. 插件开发注意事项

• 区分 Node App 与 Client App。
• 不在服务端阶段直接使用浏览器 API。
• 使用 VuePress 提供的 hooks 和生命周期。
• 测试 SSR 和客户端两种渲染模式。

4. CI 配置示例

# .github/workflows/vuepress.yml
name: Build VuePress Docs
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install
      - run: pnpm run docs:build

十三、 性能与安全

1. 性能关注点

• VuePress 构建静态 HTML，适合 CDN 静态托管。
• 客户端通过 Vue Router 提供 SPA 导航体验。
• 使用 Vite bundler 时，本地开发体验更现代；Webpack 适合已有历史兼容需求。
• Markdown 解析、代码高亮、搜索索引、图片处理会影响构建耗时。
• 大型站点应控制首页 JS 体积、全局组件数量、代码高亮语言包、图片体积和搜索索引大小。

2. 构建优化

• 使用 Vite bundler 获得更快构建速度。
• 代码高亮按需加载语言包。
• 图片压缩和懒加载。
• 控制全局组件注册数量。
• 搜索索引合理分片。

3. 安全关注点

• 不要把密钥、私有 token、后台接口凭证写入 Markdown、frontmatter 或客户端配置。
• Algolia DocSearch 等搜索配置只能暴露可公开使用的 search-only key。
• 外链处理需保留 target="_blank" 的 rel="noopener noreferrer" 行为。
• 自定义 Markdown 插件、HTML 注入、Vue 组件渲染需注意 XSS 风险。
• 依赖插件和主题应定期审计，尤其是社区插件。
• 部署侧建议配置 HTTPS、CSP、缓存策略和安全响应头。

4. XSS 防护

• 不信任用户提交的 Markdown 内容时，必须清洗 HTML 和脚本。
• 避免使用 v-html 渲染未清洗内容。
• 第三方插件和主题需要评估供应链安全。

十四、 技术对比

十五、 最佳实践

1. 新项目不要直接 pnpm add -D vuepress： 这会安装 1.x；VuePress 2 使用 vuepress@next。

2. 锁定版本并记录升级策略： RC 阶段不要无控制自动升级。

3. 优先使用 Vite bundler： 只有明确兼容需求时再选择 Webpack。

4. Markdown 内嵌 Vue 组件要控制边界： 避免把文档站变成复杂应用。

5. 主题自定义优先扩展默认主题： 除非确实需要全自定义布局。

6. 插件选择优先官方 ecosystem： 再评估社区插件维护状态。

7. 多语言站点统一规划： 路径、导航、搜索索引和 sitemap 要统一规划。

8. 大型文档站启用搜索前确认索引策略： DocSearch / Meilisearch 需要先确认索引更新和权限策略。

9. 公开站点补齐 SEO： title、description、canonical、sitemap、robots。

10. CI 中固定执行 build： 避免 Markdown、frontmatter、插件配置错误延迟到部署时暴露。

11. 插件开发时区分 Node App 与 Client App： 不在服务端阶段直接使用浏览器 API。

12. 迁移评估： 已有 VuePress 1 项目应评估迁移到 VuePress 2 或 VitePress，而不是长期停留在 Vue 2 + Webpack 的旧栈。

十六、 学习与社区资源

1. 官方核心资源

• VuePress 官方文档：https://vuepress.vuejs.org/
• VuePress GitHub：https://github.com/vuepress/core
• VuePress Ecosystem：https://ecosystem.vuejs.press/
• VuePress Marketplace：https://marketplace.vuejs.press/
• VuePress v1 文档：https://v1.vuepress.vuejs.org/
• VuePress 迁移指南：https://vuepress.vuejs.org/guide/migration.html

2. 相关生态资源

• VitePress 文档：https://vitepress.dev/
• Docusaurus 文档：https://docusaurus.io/docs
• MkDocs 文档：https://www.mkdocs.org/
• Astro Starlight：https://starlight.astro.build/

3. 社区与主题

• VuePress Discord / Vue Land Discord：社区讨论。
• Hope Theme：https://theme-hope.vuejs.press/
• Plume Theme：https://plume.pengzhanbo.cn/
• Reco Theme：https://vuepress-theme-reco.recoluan.com/

4. 推荐实践

• 优先参考 VuePress 2 官方文档和 Ecosystem 文档。
• 关注 GitHub Releases 和 changelog，RC 阶段升级风险较高。
• 对比 VitePress 后选择 VuePress 2，确保项目确实需要其特定生态能力。