VuePress 文档站 5 章搭建 - 2026 整站源码实战指南，含 5 大关键点 + 自查清单 + 速查手册，新手必学。
# VuePress 文档站 5 章搭建
VuePress 是 Vue 团队出的文档站生成器，项目文档首选（Vue 官方、Vite 官方都用）。本文讲 VuePress 2.x 5 章搭建。
第 1 招：判断标准（用 VuePress）
3 个场景 VuePress 是首选：
1. 项目文档（开源项目必备）
2. 知识库（公司内部文档）
3. 个人技术博客（喜欢 Vue 生态）
VuePress vs 其他：
| 文档站 | 上手 | 速度 | 主题数 |
|---|---|---|---|
| VuePress 1.x | 简单 | 中 | 50+ |
| VuePress 2.x | 中等 | 快 | 80+ |
| Docusaurus | 中等 | 中 | 50+ |
| MkDocs | 简单 | 快 | 30+ |
第 2 招：避坑点（主题 + 部署）
1. VuePress 1.x 和 2.x API 完全不兼容
2. 主题装错版本（v1 主题不能在 v2 用）
3. 图片路径：必须用相对路径（`./img.png`），不能用绝对路径（`/img.png`）
4. Node.js 必须 ≥ 18
第 3 招：关键参数（6 款主题对比）
| 主题 | 大小 | 适合 |
|---|---|---|
| default | 100KB | 官方文档 |
| vdoing | 150KB | 知识库 |
| hope | 120KB | 博客 + 文档 |
| reco | 100KB | 个人博客 |
| blogue | 120KB | 技术博客 |
| yuchanns | 80KB | 检索 |
第 4 招：易踩坑（配置 + 部署）
```js
// .vuepress/config.js 关键配置
export default {
title: '我的文档站',
description: 'VuePress 文档站',
lang: 'zh-CN',
base: '/', // 部署子路径改 /docs/
theme: 'hope', // 默认 default
sitemap: { hostname: 'https://yourname.github.io' },
}
```
4 个易踩坑：
1. 部署子路径 — `base` 改 `/docs/`
2. 图片 404 — 用相对路径
3. 主题装不上 — VuePress 2 必须用 v2 主题
4. 构建失败 — Node.js 必须 ≥ 18
第 5 招：场景建议（3 个组合）
| 场景 | 主题 | 部署 |
|---|---|---|
| 官方文档 | default | GitHub Pages |
| 个人博客 + 文档 | hope | Vercel |
| 知识库 | yuchanns | Netlify |
下载包里有什么
[VuePress 5 章搭建速查 PDF]：5 页速查
[VuePress 主题 6 款速查.md]：6 款主题实测
[vuepress-config.js]：完整推荐配置
[VuePress 部署指南.md]：3 种部署方式
[VuePress 常用命令.bat]：一键部署脚本
为什么必须下载
VuePress 网上资料多但完整配置少，且 VuePress 1.x / 2.x 资料混在一起。下载包是 VuePress 2.x 专用，提供完整 `config.js` + 6 款主题对比 + 3 种部署（GitHub Pages / Vercel / Netlify）。一键部署批处理直接双击运行。
本文配套下载包按 4 件套打包：PDF 速查 + VuePress 主题速查 + 完整配置 + 部署指南 + 一键部署脚本。打开即用。
