VuePress
由 Vue 驱动、支持 Vite 与 Webpack Bundler，并拥有独立插件和主题生态的静态站点生成器。
项目概述
VuePress 以 Markdown 为内容中心，将文件路由编译为预渲染 HTML 和 Vue 单页应用。它把核心、Bundler、主题和插件拆分为独立层，适合需要灵活扩展的文档、博客与静态网站。
VuePress 由社区维护并采用 MIT 许可证，最初为 Vue 及其子项目文档而创建。VuePress 2 使用 Vue 3 和 Vue Router，将每个 Markdown 文件解析为 HTML 后作为 Vue 组件模板处理；开发阶段以 SPA 运行，生产构建则为每条路由生成服务端渲染的静态 HTML。它把核心能力与 Bundler、主题和插件解耦，可在 Vite 与 Webpack 之间选择，并通过官方生态仓库组合默认主题、搜索、PWA 等能力。
主要特点
VuePress 通过分层架构、Vue 增强 Markdown 和插件生态，为内容网站提供可组合的构建基础。
Markdown 文件路由
内容文件的相对路径自动生成页面路由，README.md 对应目录首页，并支持 Frontmatter 控制页面元数据。
Vue 增强内容
Markdown 会作为 Vue 组件模板处理，可以使用模板语法、内置组件和自行注册的 Vue 组件。
静态预渲染与 SPA
构建时为各路由生成 HTML，首次访问利于 SEO，客户端接管后使用 Vue Router 进行页面切换。
可替换 Bundler
核心不绑定单一构建器，官方同时维护 Vite 与 Webpack Bundler，团队可按兼容性和工具链选择。
主题系统
主题本质上是返回 VuePress Plugin 的函数，可提供布局、客户端代码、样式与默认配置，并支持继承。
插件生命周期
插件可扩展配置、Markdown、页面、客户端文件、Bundler 选项和构建生命周期，并被主题复用。
客户端配置入口
client.ts 可增强 Vue 应用、注册组件、运行组合式逻辑、添加根组件，并访问路由与站点数据。
站点与主题国际化
路径 Locale 定义不同语言的标题、描述和内容目录，主题再提供语言切换器与界面文本。
适用场景
适合希望继续使用 Vue 组件，同时需要选择 Bundler、主题或大量内容插件的文档与静态站点。
Vue 生态项目文档
适合安装指南、组件说明、配置参考和可运行 Vue 示例，与现有组件库共享技术栈。
插件驱动的文档门户
当站点需要搜索、PWA、评论、代码演示或自定义 Markdown 转换时，可从生态中组合插件。
需要 Webpack 兼容的迁移项目
可选择 Webpack Bundler 承接依赖特定 Loader 或旧构建集成的 VuePress 1 网站。
团队知识库
Markdown、Git、导航和静态输出适合工程规范、架构决策、运行手册和内部培训材料。
博客与内容网站
自定义主题、页面数据和插件可以建立文章列表、标签、归档、作者信息和订阅能力。
多语言项目站
Locale 目录和主题国际化配置适合维护不同语言的首页、文档导航及界面文本。
优点与注意事项
技术选型不仅要看能力，也要理解它带来的团队成本。
主要优点
VuePress 擅长的地方
- Markdown 与 Vue 组件自然组合，适合 Vue 开发团队
- Vite 和 Webpack Bundler 可选，能兼顾新项目速度与旧生态兼容
- 核心、主题、插件和 Bundler 分层清晰，扩展边界明确
- 官方生态提供主题、搜索及多种常见功能插件
- 静态 HTML 部署简单，并保留 Vue Router 的客户端导航体验
- TypeScript 配置、插件与主题 API 便于构建可维护的内容平台
需要注意
采用前应考虑的问题
官方明确说明配置和 API 尚未完全稳定，RC 版本升级仍可能包含小型破坏性变化。
核心、Bundler、默认主题和插件分别发布，混用不同 RC 代际可能产生类型、构建或运行错误。
核心、官方生态、市场和社区主题分别维护，采用插件前应核对目标 VuePress 版本和最近维护状态。
VuePress 2 使用 Vue 3，主题、插件和配置 API 均有变化，应按迁移指南逐项替换而不是只更新依赖。
页面会在 Node.js 中预渲染，直接访问 window 或 document 的逻辑应放入客户端生命周期或专用组件。
Bundler、主题和插件都需显式安装与配置；如果只需快速轻量文档，VitePress 通常更直接。
快速开始
使用官方创建工具初始化项目，配置 Vite Bundler 和默认主题，编写 Vue 增强 Markdown，再加入客户端配置与多语言入口。
bashnpm init vuepress open-docs
cd open-docs
npm install
npm run docs:devbashmkdir open-docs
cd open-docs
npm init -y
npm install -D vuepress@next
npm install -D @vuepress/bundler-vite@next
npm install -D @vuepress/theme-default@next
mkdir -p docs/.vuepresstypescript// docs/.vuepress/config.ts
import {viteBundler} from "@vuepress/bundler-vite";
import {defaultTheme} from "@vuepress/theme-default";
import {defineUserConfig} from "vuepress";
export default defineUserConfig({
lang: "zh-CN",
title: "Open Docs",
description: "清晰、可扩展的项目文档",
bundler: viteBundler(),
theme: defaultTheme({
navbar: [
{text: "指南", link: "/guide/"},
{text: "参考", link: "/reference/"},
],
sidebar: {
"/guide/": [
{
text: "使用指南",
children: [
"/guide/README.md",
"/guide/getting-started.md",
],
},
],
},
repo: "open-docs/website",
}),
});markdown---
title: 快速开始
description: 安装并运行 Open Docs
---
<script setup>
import {ref} from "vue";
const count = ref(0);
</script>
# 快速开始
VuePress 会把 Markdown 编译为 Vue 组件模板。
当前点击次数：{{ count }}
<button @click="count++">增加</button>
::: tip
普通内容仍然保持清晰的 Markdown 写法。
:::typescript// docs/.vuepress/client.ts
import {defineClientConfig} from "vuepress/client";
import VersionBadge from "./components/VersionBadge.vue";
export default defineClientConfig({
enhance({app}) {
app.component("VersionBadge", VersionBadge);
},
setup() {
// 在客户端应用根部运行组合式逻辑
},
rootComponents: [],
});typescript// docs/.vuepress/config.ts
import {viteBundler} from "@vuepress/bundler-vite";
import {defaultTheme} from "@vuepress/theme-default";
import {defineUserConfig} from "vuepress";
export default defineUserConfig({
bundler: viteBundler(),
locales: {
"/": {
lang: "zh-CN",
title: "Open Docs",
description: "项目文档",
},
"/en/": {
lang: "en-US",
title: "Open Docs",
description: "Project documentation",
},
},
theme: defaultTheme({
locales: {
"/": {selectLanguageName: "简体中文"},
"/en/": {selectLanguageName: "English"},
},
}),
});json{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}bashnpm run docs:build
# 构建结果位于 docs/.vuepress/dist
# 使用任意静态文件服务器预览或部署下一步：VuePress 2 仍处于 RC 阶段，应固定 vuepress、Bundler、主题和官方插件的确切版本，并在每次升级前阅读 Changelog、执行完整构建和检查主题 API。
类似项目
这些项目同样构建 Markdown 内容站；VuePress 的主要差异是可替换 Bundler 与更独立的插件、主题体系。
VitePress
基于 Vite 与 Vue、面向技术文档和内容网站的快速静态站点生成器。
查看项目Docusaurus
由 Meta 维护，使用 React、MDX 和插件系统构建文档及内容网站的静态站点生成器。
查看项目MkDocs
使用 Python、Markdown 和 YAML 配置构建项目文档的静态站点生成器。
查看项目Markdoc
由 Stripe 开源、基于 Markdown 的声明式内容创作框架与渲染工具链。
查看项目Vue.js
渐进式 JavaScript 框架，易学易用且拥有优秀的性能表现。
查看项目Vite
新一代前端构建工具，提供快速开发服务器和优化构建。
查看项目Rspress
基于 Rspack、React 和 MDX，强调快速构建与现代文档体验的静态站点生成器。
访问官网Docsify
在浏览器中直接加载 Markdown、无需静态预构建的轻量文档网站工具。
访问官网VuePress vs VitePress
VuePress 与 VitePress 都以 Markdown、Vue 和静态预渲染构建内容网站。VuePress 2 强调可替换 Bundler、独立主题与插件生态；VitePress 与 Vite 深度集成，更强调轻量配置、构建速度和精致的默认文档体验。
| 比较维度 | VuePress | VitePress |
|---|---|---|
| 维护团队 | 独立 VuePress 社区团队 | Vue.js 核心团队 |
| 版本状态 | 2.0 RC，API 仍可能小幅调整 | 1.6.4 稳定线，2.0 Alpha 并行开发 |
| Bundler | 官方支持 Vite 或 Webpack | 与 Vite 深度绑定 |
| 扩展体系 | 独立 Plugin、Theme、Bundler 与生态仓库 | Vite Plugin、默认主题扩展和自定义 Vue 主题 |
| Markdown 组件 | Markdown 作为 Vue 组件模板处理 | Markdown 作为 Vue SFC 处理并优化静态内容 |
| 默认体验 | 显式组合核心、Bundler 与主题 | 更集成的技术文档主题与代码功能 |
| 迁移与兼容 | 可用 Webpack 承接部分旧工具链需求 | 更适合全新 Vite/Vue 3 内容项目 |
| 更适合 | 重视插件、主题和 Bundler 可替换性 | 追求快速、轻量和默认文档体验 |
如果现有 VuePress 项目依赖主题、插件或 Webpack，或者团队希望自建可复用的内容平台扩展层，VuePress 2 更具可组合性；如果新项目主要需要快速技术文档、Vite 开发体验和更少配置，VitePress 通常更直接。由于两者都存在下一代预发布线，选型时应锁定版本并用真实主题、插件和内容规模验证升级成本。
资料核验
版本、维护信息与本页采用的官方资料来源。
本次核验覆盖 VuePress 2 的 RC 状态、Node.js 要求、Markdown 与 Vue 渲染方式、Vite/Webpack Bundler、主题、插件、客户端配置和国际化能力。官方仓库仍有近期提交，但 RC API 可能变化，升级前应固定整套包版本并阅读 Changelog。
官方仓库未归档，核验时最近可见的代码活动日期为 2026 年 7 月 24 日。该状态表示项目近期仍有公开维护活动，不代表固定发布频率或长期支持承诺。