从零开始：VitePress环境搭建与基础配置
环境准备：5分钟搞定依赖安装
你可能会问，为什么非要用VitePress？我之前也试过其他工具，像Docsify虽然轻便，但定制化太差；GitBook功能全但加载慢，用户体验不好。直到去年接触VitePress，才发现它完美平衡了简单和强大——基于Vite构建，热更新速度快到离谱，改完Markdown文件，浏览器里1秒内就能看到效果，这对边写边调的文档创作太重要了。
第一步肯定是装环境，别担心，比装微信还简单。VitePress依赖Node.js，所以得先确保你电脑上有Node.js 18.0.0以上版本（划重点，低于这个版本可能会遇到依赖冲突）。你可以打开终端，输入node -v检查，比如我现在的版本是v20.10.0，完全够用。如果没有或者版本太低，去Node.js官网（https://nodejs.org/，nofollow）下LTS版本，一路下一步安装就行，记得勾选“Add to PATH”，不然终端找不到node命令。
装好Node.js后，创建项目文件夹，比如叫“my-docs”，然后在终端进入这个文件夹，输入npm init vitepress@latest，跟着提示走就行。这里有个小技巧，项目名称 用英文小写，别带空格，不然后面部署可能出问题。我第一次帮朋友搭的时候，他非要用“我的项目文档”当文件夹名，结果npm install直接报错，后来改成“my-project-docs”才好。
安装过程中会问你要不要用TypeScript配置文件，零基础选“No”就行，用JavaScript足够了；主题选“Default Theme + TypeDoc”（默认主题带TypeDoc支持，适合技术文档）；是否初始化Git仓库？ 选“Yes”，方便后续版本管理。等待1-2分钟，依赖安装完成后，输入npm run docs:dev，终端会显示“Local: http://localhost:5173/”，打开浏览器就能看到默认文档页面了——恭喜，你已经迈出第一步！
核心配置：3个文件掌控文档框架
现在页面有了，但肯定不是你想要的样子。别慌，VitePress的核心配置就3个文件，搞懂它们就能掌控整个文档框架。
第一个是package.json，这里主要看scripts里的命令：docs:dev是本地开发，docs:build是打包，docs:preview是预览打包后的效果。你以后写文档主要用npm run docs:dev，改配置后可能需要重启服务才能生效。
第二个是docs/index.md，这是文档的首页。你可以把默认内容删掉，按Markdown格式写自己的首页，比如加个项目介绍、快速开始按钮。我朋友的项目首页就放了个醒目的“开始使用”按钮，链接到/guide/，用户一进来就知道该点哪里。
第三个，也是最重要的：docs/.vitepress/config.js（如果之前选了TypeScript就是config.ts），所有导航、主题、功能配置都在这里。打开文件你会看到默认有title（文档标题）、description（SEO描述）、themeConfig（主题配置）这几个核心字段。我来一个个说：
title
和description很重要，直接影响搜索引擎收录。比如你项目叫“FastUI”，title可以写“FastUI
themeConfig
里的nav（导航栏）和sidebar（侧边栏）是用户浏览的核心。比如你想在顶部导航加“指南”“API”“关于”，就在nav数组里加对象：
nav: [
{ text: '指南', link: '/guide/' },
{ text: 'API', link: '/api/' },
{ text: '关于', link: '/about/' }
]
注意link的路径要和你文件夹结构对应——比如写/guide/，就需要在docs文件夹下建guide文件夹，里面放index.md，不然点击会404。我之前帮朋友调导航时，他把link写成了/guide（少个斜杠），结果本地能打开，部署后就报错，查了半天才发现是路径格式问题。
侧边栏配置稍微复杂点，如果想给“指南”目录配侧边栏，就在sidebar里加：
sidebar: {
'/guide/': [
{
text: '开始使用',
items: [
{ text: '安装', link: '/guide/install' },
{ text: '快速上手', link: '/guide/quick-start' }
]
}
]
}
这样用户点导航栏的“指南”，侧边栏就会显示“开始使用”下的两个子项。VitePress官方文档（https://vitepress.dev/reference/default-theme-config，nofollow）里有更详细的配置示例，你可以照着改。
进阶优化：内容创作、样式定制与部署上线
Markdown进阶：让文档从“能用”到“好用”
基础框架搭好了，接下来就是写内容。VitePress支持增强版Markdown，比普通Markdown强大太多，学会这些技巧，文档可读性直接翻倍。
最常用的是代码块——技术文档少不了代码示例，VitePress的代码块支持语法高亮、行号、代码折叠，甚至实时预览。比如你想展示一段Vue代码，带行号和高亮第2行：
vue{2}
const count = ref(0)
在后面加语言名（vue），花括号里写行号，效果立马专业。我朋友的文档里有很多代码示例，一开始直接贴文本，用户反馈看不清，后来用了这个功能，评论区都说“代码终于能看了”。collapse如果代码太长，可以加
让它默认折叠：js collapse，点击才展开。还能加title显示文件名：ts title="utils.ts"，用户一看就知道这段代码来自哪个文件。除了代码，图表也很重要。VitePress内置mermaid支持，直接用
mermaid就能画流程图、时序图。比如画个“文档写作流程”：
mermaid
graph TD
A[确定章节结构] > B[写Markdown内容]
B > C[插入代码/图表]
C > D[本地预览调整]
D > E[部署上线]
比用图片方便多了，还不用担心缩放模糊。对了，VitePress还能直接用Vue组件！比如想在文档里加个提示框，用
组件：
md
注意：这里需要Node.js 18+环境，低于此版本可能会报错。
type可以是info/warning/danger，颜色会自动变化。我在“环境准备”章节就用了这个，用户一眼就能看到关键提示。docs/.vitepress/theme/custom.css样式定制：3步让文档颜值提升一个档次
默认主题虽然简洁，但可能和你的项目风格不搭。别担心，3步就能改成你想要的样子，不用写复杂CSS。
第一步：改主题色。VitePress用CSS变量控制颜色，你可以在
里覆盖变量。比如把主色调改成项目品牌色：
css
:root {
vp-c-brand: #646cff; / 你的品牌色 /
vp-c-brand-light: #747bff;
vp-c-brand-dark: #535bf2;
}
改完保存，热更新会自动生效，你可以实时调整颜色直到满意。我帮朋友改的时候，他的项目主色是绿色，我试了3个色值才找到既醒目又不刺眼的#3eaf7c。
第二步：改导航栏/侧边栏样式。如果觉得导航栏太高，在custom.css里加：
css
:root {
vp-nav-height: 56px; / 默认64px，改小更紧凑 /
}
想让侧边栏文字大一点：css
.vp-sidebar-item-link {
font-size: 15px; / 默认14px /
}
改之前最好用浏览器“检查”功能（F12）看看元素类名，别瞎写。
第三步：自定义首页布局。默认首页有点单调，你可以用VitePress的首页组件（Home）改得更吸引人。在index.md开头加：
md
hero:
name: “FastUI”
text: “轻量级Vue3组件库”
tagline: 50+组件，按需引入，性能优先
actions:
text: 开始使用
link: /guide/
text: 查看组件
link: /components/
这样首页会显示大标题、副标题和两个按钮，比默认的列表好看多了。具体参数可以看VitePress首页配置文档（https://vitepress.dev/reference/default-theme-home-page，nofollow）。一键部署：3种免费方案任你选
文档写好了，总得让别人看到。VitePress部署超简单，3种免费方案，选一个你熟悉的就行。
GitHub Pages
：适合有GitHub账号的用户。先在config.js里加base: ‘/仓库名/’（比如仓库叫my-docs，就写base: ‘/my-docs/’，这步很重要，不然部署后样式会乱）。然后在package.json的scripts里加部署命令：json
“scripts”: {
“docs:build”: “vitepress build docs”,
“docs:deploy”: “npm run docs:build && gh-pages -d docs/.vitepress/dist”
}
安装gh-pages：
npm install gh-pages -D，然后运行npm run docs:deploy，等几分钟，去GitHub仓库的“Settings-Pages”就能看到部署地址了。我朋友第一次部署时忘了改base，结果页面全是白的，后来改了才正常——你可别犯这个错。npm run docs:build
Netlify：更简单，直接把代码推到GitHub，然后在Netlify（https://www.netlify.com/，nofollow）导入仓库，设置构建命令为，输出目录为docs/.vitepress/dist，点部署就行。Netlify还支持自动部署，以后改了文档推到GitHub，它会自动重新构建，省得手动跑命令。
Vercel：和Netlify类似，导入GitHub仓库，配置构建命令和输出目录，免费版足够个人和小团队用。我自己的文档用的就是Vercel，访问速度比GitHub Pages快，尤其国内用户打开更快。
部署完记得检查链接是否能打开，图片、代码块显示是否正常。可以用谷歌站长工具（如果有的话）或者W3C Link Checker（https://validator.w3.org/checklink/，nofollow）扫一遍死链，别让用户点进去404。
按这个流程走，你今天就能搭出第一版文档，从环境搭建到上线全程不超过3小时。记得遇到问题先看VitePress的官方 troubleshooting（https://vitepress.dev/guide/troubleshooting，nofollow），解决不了可以在评论区问我，我看到都会回。最后说一句，文档不是写完就完事了，定期更新内容、优化导航，用户体验才会越来越好——你准备好用VitePress搭什么文档了？
部署后打开文档，发现文字挤在一起、导航栏全乱了，或者点链接直接跳404？这八成是没配置好 base 参数，我去年帮同事搭开源项目文档时就踩过这个坑。当时他把代码推到GitHub后，部署页面一片混乱，标题都跑到左上角去了，查了半天发现是 config.js 里漏了 base 设置。VitePress默认把网站当根目录部署，但我们通常是部署在子路径下（比如GitHub Pages的 username.github.io/仓库名/），这时候必须在 docs/.vitepress/config.js 里加一行 base: '/仓库名/'——仓库名叫 react-tools-docs 就写 base: '/react-tools-docs/'，名字得和GitHub仓库完全一致，大小写都不能错，不然浏览器加载CSS、JS文件时会跑到根目录去找，自然就找不到资源了。我后来帮他加上这行配置，重新部署后刷新页面，样式立马恢复正常，导航栏也规规矩矩地显示在顶部了。
另一个容易踩的坑是Markdown里的链接用了绝对路径。你在本地预览时写 安装教程 可能没问题，因为本地开发服务器是根路径，但部署到子目录后，实际访问路径是 https://你的域名/仓库名/guide/install，这时候 /guide/install 会被浏览器解析成 https://你的域名/guide/install，少了仓库名这一层，可不就404了嘛。我 所有内部链接都用相对路径，比如当前文件在 guide/quick-start.md，想链接到同目录的 install.md，就写 安装教程；想链接到上一级的 api/index.md，就写 API文档。相对路径的好处是不管你部署在哪个层级，它都会根据当前文件位置自动计算路径，比绝对路径灵活多了。上个月帮一个做工具库的朋友改文档链接，他原来全用绝对路径，部署到Netlify后5个链接里3个404，改成相对路径后一次性解决，现在每次写新文档他都会先问我：“这个链接用 ./ 还是 ../ 来着？”
VitePress和Docsify、GitBook相比，有什么优势？
VitePress的核心优势在于“快”和“轻量”。基于Vite构建，热更新速度比GitBook快5-10倍，改完Markdown文件1秒内即可预览效果；同时比Docsify更支持定制化，可通过Vue组件扩展功能，又比GitBook体积小（打包后通常仅几MB），加载速度更快。适合需要平衡简单性和专业性的技术文档场景。
安装VitePress时提示“Node.js版本过低”怎么办？
VitePress要求Node.js 18.0.0及以上版本，若版本过低，需先卸载旧版本，到Node.js官网（https://nodejs.org/，nofollow）下载LTS版本（ 选择18.x或20.x系列），安装时勾选“Add to PATH”选项，确保终端能识别node命令。安装完成后重启终端，输入node -v确认版本达标即可。
部署后文档样式错乱，链接点击404怎么解决？
大概率是未配置base参数导致。在docs/.vitepress/config.js中添加base: '/仓库名/'（如GitHub仓库名为“my-docs”，则写base: '/my-docs/'），确保与部署平台的访问路径一致。另外检查Markdown中的链接路径是否使用相对路径（如../guide/install），避免绝对路径导致本地正常但部署后失效。
Markdown中插入的Vue组件（如）不显示怎么办？
首先确认VitePress版本是否为1.0.0及以上（旧版本可能不支持部分组件），可通过npm list vitepress检查版本，低版本需运行npm update vitepress升级。其次确保组件标签正确闭合（如而非），且未遗漏type等必要属性（如）。若仍不显示，检查是否在非Markdown文件中使用（仅支持在.md文件内直接使用内置组件）。
本地预览时热更新失效，改了内容浏览器不刷新怎么处理？
先检查终端是否有报错（如文件权限问题），若终端正常运行，尝试按Ctrl+C终止服务，删除node_modules和.vitepress/dist文件夹，重新运行npm install和npm run docs:dev。若仍失效，可能是文件路径包含中文或特殊字符， 将项目文件夹重命名为英文小写（如“my-docs”），避免空格和中文。
