什么是 VitePress
VitePress 是一个基于 Vite 构建的静态站点生成器（SSG，Static Site Generator），专为技术文档设计。它由 Vue.js 团队开发和维护，是 VuePress 的下一代继任者。
核心定义
VitePress = Vite（构建工具）+ Vue 3（组件框架）+ Markdown（内容源）→ 静态 HTML 站点静态站点生成器（SSG）
SSG 是一种在构建时将内容预渲染为静态 HTML 文件的工具。与动态网站不同，静态站点无需服务器端运行时，具有部署简单、性能优异、安全性高等优点。
技术架构
整体架构图
┌─────────────────────────────────────────────────────────────────┐
│ VitePress 架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Markdown │ │ Vue SFC │ │ 静态资源 │ │
│ │ (.md) │ │ (.vue) │ │ (图片/样式) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Vite 开发服务器 │ │
│ │ (HMR / 按需编译) │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Markdown │ │ Vue 3 │ │ 主题 │ │
│ │ 编译器 │ │ 渲染器 │ │ 系统 │ │
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
│ │ │ │ │
│ └─────────────────┼─────────────────┘ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ 预渲染 (SSG) │ │
│ │ 生成静态 HTML │ │
│ └──────────┬───────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ 静态站点输出 │ │
│ │ (HTML/CSS/JS/资源) │ │
│ └──────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘核心技术栈
| 层级 | 技术 | 说明 |
|---|---|---|
| 构建工具 | Vite | 基于 ES Modules 的下一代前端构建工具 |
| 框架 | Vue 3 | 渐进式 JavaScript 框架 |
| 渲染引擎 | @vue/server-renderer | Vue 3 服务端渲染 |
| 路由 | Vue Router | 基于文件系统的路由 |
| 内容源 | Markdown | 支持 frontmatter 的增强 Markdown |
工作流程
开发模式
用户请求 → Vite Dev Server → 按需编译 → 热更新 (HMR) → 浏览器
↓
实时编译 Markdown/Vue 组件
↓
无需完整构建，毫秒级响应生产构建
Markdown + Vue 组件
↓
Vite 构建 pipeline
↓
Vue SSR 预渲染
↓
生成静态 HTML + 注水 JS
↓
优化输出（压缩、代码分割、资源优化）核心特点
1. 极速的开发体验
VitePress 利用 Vite 的即时热更新能力，开发服务器启动速度极快：
bash
# 启动开发服务器，毫秒级响应
npm run docs:dev为什么这么快？
| 特性 | 说明 |
|---|---|
| ESM 原生支持 | 开发模式下无需打包，浏览器直接加载 ES Modules |
| 按需编译 | 只编译当前页面用到的文件，而非整个项目 |
| 高效 HMR | 模块级别的热更新，更新速度与项目大小无关 |
| 缓存优化 | 利用浏览器缓存和预构建依赖缓存 |
2. Vue 3 驱动
VitePress 深度集成 Vue 3 生态：
vue
<!-- 在 Markdown 中直接使用 Vue 组件 -->
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>
<button @click="count++">点击次数: {{ count }}</button>Vue 3 带来的优势：
| 特性 | 说明 |
|---|---|
| Composition API | 更灵活的组件逻辑组织方式 |
| 更好的 TypeScript | 完整的类型推断支持 |
| 更小的包体积 | Tree-shaking 友好 |
| 更快的渲染 | 优化的虚拟 DOM 和编译器 |
3. Markdown 增强
VitePress 扩展了标准 Markdown 语法：
markdown
<!-- 自定义容器 -->
::: tip 提示
这是一个提示框
:::
<!-- 代码组 -->
::: code-group
```npm
npm install vitepressyarn
yarn add vitepresspnpm
pnpm add vitepress:::
**增强功能一览：**
| 功能 | 语法 | 说明 |
|------|------|------|
| 自定义容器 | `::: tip` / `::: warning` | 信息提示框 |
| 代码组 | `::: code-group` | 多语言代码切换 |
| 代码高亮 | `{1,3-5}` | 行高亮标记 |
| 数学公式 | `$E=mc^2$` | KaTeX 支持 |
| Mermaid 图表 | ` ```mermaid ` | 流程图、时序图 |
| 导入代码片段 | `<<< @/path` | 导入外部代码文件 |
### 4. 主题系统默认主题 ├── 布局组件 │ ├── Layout.vue # 主布局 │ ├── Home.vue # 首页布局 │ └── Doc.vue # 文档页布局 ├── 导航组件 │ ├── Nav.vue # 顶部导航 │ ├── Sidebar.vue # 侧边栏 │ └── Outline.vue # 大纲目录 ├── 功能组件 │ ├── Search.vue # 搜索 │ └── CarbonAds.vue # 广告位 └── 样式系统 ├── CSS 变量 # 主题定制 └── 深色模式 # 自动切换
**主题定制方式：**
```ts
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
// 1. 扩展默认主题
export default {
extends: DefaultTheme,
// 添加自定义组件
enhanceApp({ app }) {
app.registerGlobalComponent('MyComponent', () =>
import('./components/MyComponent.vue')
)
}
}5. 性能优化
VitePress 内置多种性能优化：
| 优化项 | 说明 |
|---|---|
| 预渲染 | 构建时生成静态 HTML，首屏无需 JS |
| 注水优化 | 客户端仅加载必要的交互代码 |
| 代码分割 | 按页面自动分割，避免大包 |
| 资源优化 | 自动处理图片、字体等资源 |
| 预加载 | 预加载下一页资源，提升导航速度 |
与其他工具详细对比
SSG 工具对比矩阵
| 特性 | VitePress | VuePress | Docusaurus | Nuxt Content | Next.js |
|---|---|---|---|---|---|
| 构建工具 | Vite | Webpack | Webpack | Vite/Nitro | Webpack/Turbopack |
| 框架 | Vue 3 | Vue 2 | React | Vue 3/Nuxt | React |
| 热更新 | ⚡ 极快 | 较慢 | 快 | ⚡ 极快 | 快 |
| 学习曲线 | 低 | 低 | 中 | 中 | 中高 |
| MDX 支持 | ❌ | ❌ | ✅ | ✅ | ✅ |
| Vue 组件 | ✅ 原生 | ✅ 原生 | ❌ | ✅ 原生 | 需配置 |
| 国际化 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 搜索 | 本地/Algolia | 插件 | 本地/Algolia | 本地 | 需配置 |
| 版本管理 | 需配置 | 需配置 | ✅ 内置 | 需配置 | 需配置 |
| 主题系统 | 灵活 | 灵活 | 固定 | 灵活 | 灵活 |
| 部署难度 | 简单 | 简单 | 简单 | 中等 | 中等 |
选型建议
选择 VitePress，如果你...
- 需要技术文档站点或博客
- 熟悉 Vue 生态
- 追求极致的开发体验
- 需要在 Markdown 中使用 Vue 组件
选择 Docusaurus，如果你...
- 需要 React 生态
- 需要版本管理功能
- 团队主要使用 React
选择 Nuxt Content，如果你...
- 需要全栈应用能力
- 需要动态内容支持
- 项目基于 Nuxt 生态
性能对比
以下是基于相同内容构建的基准测试：
| 指标 | VitePress | VuePress | Docusaurus |
|---|---|---|---|
| 开发启动 | ~300ms | ~3s | ~2s |
| 热更新 | ~50ms | ~500ms | ~200ms |
| 构建时间 (100页) | ~5s | ~15s | ~10s |
| 输出体积 | 最小 | 中等 | 较大 |
适用场景
理想场景
┌─────────────────────────────────────────────────────────┐
│ VitePress 最佳适用场景 │
├─────────────────────────────────────────────────────────┤
│ │
│ 📚 技术文档 框架库文档、API 文档、开发指南 │
│ 📝 个人博客 技术博客、知识笔记、学习心得 │
│ 🏠 项目主页 开源项目官网、产品介绍页 │
│ 📖 教程网站 在线课程、学习路径、培训资料 │
│ 📋 知识库 团队知识库、内部文档、Wiki │
│ 🎨 作品集 个人作品展示、项目案例 │
│ │
└─────────────────────────────────────────────────────────┘不适用场景
可能不适合的场景
- 电商网站：需要动态数据、购物车等功能
- 社交平台：需要用户系统、实时交互
- CMS 内容管理：需要后台管理、多用户协作
- 动态应用：需要服务端渲染 (SSR) 的复杂应用
发展历程
2017 2018 2020 2022 2024+
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌─────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│Vue │───→│ VuePress │─────→│VitePress│─────→│VitePress│────→│VitePress│
│文档│ │ 1.x │ │ Alpha │ │ 1.0 │ │ 2.0+ │
└─────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │ │
│ │ │ │
▼ ▼ ▼ ▼
Vue 2 + Vue 3 + Vite 稳定版本 新特性：
Webpack 实验版本 正式发布 - MPA 模式
- 改进 i18n
- llms.txt版本演进
| 版本 | 时间 | 重大更新 |
|---|---|---|
| 1.0 | 2023.12 | 正式稳定版发布 |
| 1.2 | 2024.03 | 改进搜索、性能优化 |
| 1.6 | 2024.12 | 增强多语言支持 |
| 2.0 | 2025+ | MPA 模式、llms.txt 支持 |
快速开始
最简示例
bash
# 1. 创建项目
mkdir my-docs && cd my-docs
# 2. 初始化
npm init -y
# 3. 安装 VitePress
npm add -D vitepress
# 4. 创建首页
echo '# Hello VitePress' > index.md
# 5. 启动开发服务器
npx vitepress dev目录结构
my-docs/
├── docs/ # 文档目录
│ ├── .vitepress/ # 配置目录
│ │ └── config.mts # 配置文件
│ ├── guide/ # 指南文档
│ │ └── index.md
│ └── index.md # 首页
├── package.json
└── node_modules/为什么选择 VitePress？
推荐理由
如果你正在寻找一个简单、快速、现代化的文档站点解决方案，VitePress 是最佳选择。
决策矩阵
| 需求 | VitePress 是否满足 | 说明 |
|---|---|---|
| 快速开发 | ✅ | Vite HMR 提供极致体验 |
| 文档需求 | ✅ | 专为文档设计的功能 |
| Vue 生态 | ✅ | 原生支持 Vue 组件 |
| 高性能 | ✅ | 静态 HTML + 优化加载 |
| SEO 友好 | ✅ | 预渲染 + 结构化数据 |
| 部署简单 | ✅ | 纯静态，任意托管平台 |
| 学习成本低 | ✅ | 约定优于配置 |
| 持续维护 | ✅ | Vue 团队官方维护 |
核心优势总结
- 简单易用：约定优于配置，零配置即可开始
- 性能优异：生成的静态站点加载迅速
- 生态完善：Vue 生态，社区活跃，插件丰富
- 持续迭代：由 Vue 团队维护，长期支持有保障
- 开发体验：Vite 带来的极速 HMR，开发效率倍增
下一步
准备好开始了吗？让我们前往 安装与环境配置 章节。
本章检查清单
0 / 11 已完成0%