Vitepress 是基于 Vite 的静态站点生成器，专为技术文档与博客设计，用 Vue 单文件组件驱动页面，兼具极速热更新与生产级构建性能。它把构建速度、开发体验和内容表现力拧成一股绳：本地改一行配置、页面瞬间刷新；产物却是纯静态 HTML，丢到任意 CDN 都能跑。本文从初始化、导航配置到部署上线，带你从零跑通一个高性能文档站，并顺手填上搜索与多语言两块常被忽略的拼图。
一、为什么 Vitepress 值得一试
在 Vitepress 出现之前，技术文档站大多跑在 VuePress 1.x（基于 Webpack）上，冷启动和增量构建都偏慢。Vitepress 复用 Vite 的按需编译与 ESM 依赖预打包，把”改一行等三秒”变成了”即改即看”。更重要的是，它原生支持在 Markdown 里写 Vue 组件，文档不再只是静态文字。对内容生产者而言，这意味着示例可以”活”起来——读者看到的计数器、图表、表单就是线上真实组件，而不是截图；对维护者而言，TypeScript 类型能贯穿到文档内部，组件改了签名，文档里的用法会同步报错，从机制上杜绝了”文档与代码两张皮”。
| 方案 | 构建内核 | 技术栈 | 冷启动 | 适合的场景 |
|---|---|---|---|---|
| Vitepress | Vite | Vue 3 | 极快 | 文档站 / 技术博客 |
| VuePress 1.x | Webpack | Vue 2 | 慢 | 老项目维护 |
| Nextra | Next.js | React | 中 | React 生态文档 |
| Docusaurus | Webpack/Meta | React | 慢 | 大型开源项目 |
如果你的团队已经在用 Vue3 + Pinia 做业务开发，那么 Vitepress 几乎零迁移成本——同一套组件、同一套 TypeScript 约定都能复用。
二、五分钟初始化项目
Vitepress 官方脚手架会自动生成最小可运行结构。推荐用 pnpm 管理依赖，速度比 npm 更快：
# 交互式创建（会询问目录、模板、是否带博客）
pnpm create vitepress@latest docs
# 或手动初始化
mkdir docs && cd docs
pnpm add -D vitepress
# 本地预览
pnpm docs:dev # 等价于 vitepress dev
生成后的典型目录如下：docs/.vitepress/ 存放配置与缓存，docs/index.md 是首页，其余 .md 文件按路径映射为路由。构建产物统一输出到 .vitepress/dist/，可直接交给任意静态服务器。
三、配置导航与侧边栏
所有站点级配置集中在 .vitepress/config.ts。Vitepress 1.x 全面转向 TypeScript，类型提示能帮你少踩一半坑。建议参考 Vue3 + TypeScript 工程化 里的类型约束写法来组织配置。
import { defineConfig } from 'vitepress'
export default defineConfig({
title: '我的文档站',
description: '基于 Vitepress 构建',
themeConfig: {
nav: [
{ text: '指南', link: '/guide/' },
{ text: '博客', link: '/blog/' }
],
sidebar: {
'/guide/': [
{
text: '快速开始',
items: [
{ text: '介绍', link: '/guide/intro' },
{ text: '安装', link: '/guide/install' }
]
}
]
}
}
})
四、定制首页 Hero 与主题
Vitepress 内置了一套开箱即用的首页版式，只需在 themeConfig 里声明 hero 即可，无需手写 HTML：
themeConfig: {
hero: {
name: 'MyDocs',
text: '用 Vitepress 打造的文档站',
tagline: 'Vite 驱动 · Vue 渲染 · 开箱即用',
actions: [
{ text: '快速开始', link: '/guide/intro', theme: 'brand' },
{ text: '在 GitHub 查看', link: 'https://github.com', theme: 'alt' }
]
}
}
想换配色，覆盖 CSS 变量即可，例如在主题目录的 style.css 里设置 --vp-c-brand-1。整站主题靠一组 --vp-* 变量驱动，改一处全局生效。
五、在 Markdown 里用 Vue 组件
这是 Vitepress 区别于纯静态生成器的杀手锏：任何 .md 都能像 Vue 单文件组件一样 <script setup> 引入组件并用标签渲染，文档页因此能承载实时交互。
<!-- guide/demo.md -->
<script setup>
import Counter from '../components/Counter.vue'
</script>
# 交互示例
下方计数器是一个真实的 Vue 组件：
<Counter :start="10" />
配合 VS Code 插件 的 Volar 支持，组件 props 还能拿到类型补全，写文档体感接近写业务代码。一个实用经验是：纯说明性内容老老实实写 Markdown，只有”需要读者动手调、需要实时反馈”的部分才抽成组件——比如可交互的表单、动态图表、带状态的演示。过度组件化反而会让文档变重、SEO 变差，毕竟搜索引擎抓取的是渲染后的 HTML，组件越多越依赖客户端 hydration。
六、部署：GitHub Actions + Nginx
构建产物是纯静态文件，部署到任意平台都行。最省心的方案是用 GitHub Actions 在 push 时自动构建并发布到 Pages 分支：
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with: { version: 9 }
- run: pnpm i && pnpm docs:build
- uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: .vitepress/dist
若自建服务器托管，用 Nginx 反向代理 把根目录指到 dist/ 并开启 gzip 即可，配置极简：
server {
listen 80;
server_name docs.example.com;
root /var/www/docs;
location / {
try_files $uri $uri/ /index.html;
}
gzip on;
gzip_types text/html application/javascript text/css;
}
七、与 Vue3 工程化体系协同
Vitepress 与业务项目共享同一套 Vue 3 生态：文档站可以直接 import 业务里的展示型组件做”活文档”，也能复用 Vue3 + Pinia 的状态管理层。把组件库、工具函数抽成独立包，文档站和业务站同时依赖，既能保证示例与线上一致，又避免文档代码腐化。
八、三个常见坑
1. 子路径部署忘了设 base
部署在 https://site.com/docs/ 时，必须在 config 里设置 base: '/docs/'，否则资源路径全部 404。首页 frontmatter 写法如下：
---
title: 子路径部署
---
# 若部署在 https://site.com/docs/，需在 config 设 base: '/docs/'
2. 中文标题锚点错乱
默认中文 H2 会生成带百分号的锚点，复制链接易失效。可装 markdown-it-anchor 并自定义 slugify 为中文拼音或英文 id，保证外链稳定。
3. 大站构建内存溢出
页面超过几百篇时，单次 SSR 可能吃光内存。给构建进程加 NODE_OPTIONS=--max-old-space-size=4096，或把 build.concurrency 调小，分片渲染即可缓解。
九、接入全文搜索与多语言
文档站上线后，真正的考验是”读者能不能在三秒内找到想要的内容”。Vitepress 内置了基于 FlexSearch 的本地全文搜索，零后端、零密钥，开箱即用，对中英文混合标题都能检索。如果想做更智能的语意搜索，可接入 Algolia DocSearch，在 config 里填 index 与 key 即可替换默认引擎：
themeConfig: {
search: {
provider: 'algolia',
options: {
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_SEARCH_KEY',
indexName: 'mydocs'
}
}
}
多语言同样是一行配置的事：在 themeConfig.locale 下为每个语种声明各自的 nav、sidebar 与文案，路由自动加上 /zh/、/en/ 前缀，构建时会为每个语种生成独立站点。需要注意，i18n 下侧边栏要按语种分别配置，否则会出现中文站显示英文目录的串味问题。把搜索和语言这两块补齐，文档站才算真正长成了”产品”，而不是一份能上网的说明书。
十、结语
Vitepress 把”写文档”的体验拉到了和业务开发同级的水平：Vite 的速度、Vue 的表达力、TypeScript 的安全感，三者合一。无论是给开源项目搭文档，还是给团队做内部知识库，它都是当下性价比最高的选择。下一步可以接入全文搜索（如本地索引或 Algolia）和 i18n 多语言，让文档站真正长成产品。
