将 Vue 3 项目的使用说明、API 参考和示例代码整理成文档站点，是团队协作中绕不开的一环。VitePress 把 Vite 的按需编译、模块热替换和 Vue 3 的组件化能力结合到一起，适合用来承载组件库文档、技术手册和产品说明。它默认输出纯静态文件，不需要 Node 服务，配合一条简单的部署流水线就能上线。下面围绕初始化配置、主题定制和部署优化三个层面展开。
一、VitePress 初始化与基础配置
初始化时建议把文档目录放在项目根目录下的 docs 文件夹中，这样可以和 src、tests 等目录保持隔离。执行 npx vitepress init 后，命令行会依次询问站点名称、描述、是否使用 TypeScript、是否添加脚本等选项。完成之后会生成 .vitepress 目录以及 index.md、guide 等示例文件。下面是最小安装命令：
npm add -D vitepress vue npx vitepress init
配置文件位于 .vitepress/config.mts 或 .vitepress/config.ts。defineConfig 接收一个对象，常用字段包括 lang、title、description、head、markdown 和 themeConfig。其中 themeConfig 是默认主题的核心配置，nav 控制顶部导航，sidebar 控制侧边栏。侧边栏可以按路径分组，也可以直接写数组。VitePress 的导航和侧边栏都支持层级结构，这让多页面文档的目录组织非常灵活。
在 Vue 3 项目中，VitePress 已经内置了 Vue 3 运行时，不需要在依赖里重复安装 vue，但如果文档页面里要使用项目中的业务组件或全局组件，可以在 .vitepress/theme/index.ts 中通过 enhanceApp 注册组件。这里的组件会以 Vue 单文件组件的形式在 Markdown 中直接使用，非常适合展示组件库的交互示例。
import { defineConfig } from 'vitepress'
export default defineConfig({
lang: 'zh-CN',
title: 'My Vue 3 Docs',
description: '基于 VitePress 的组件文档站点',
themeConfig: {
nav: [
{ text: '指南', link: '/guide/' },
{ text: '组件', link: '/components/' }
],
sidebar: {
'/guide/': [
{ text: '快速开始', link: '/guide/getting-started' }
]
}
}
})
二、主题定制与扩展配置
默认主题的视觉效果可以通过 CSS 变量快速调整。VitePress 使用 --vp-c-brand 作为主品牌色，--vp-c-brand-light 和 --vp-c-brand-dark 分别对应悬停和深色模式下的颜色。把变量放到 .vitepress/theme/custom.css 中，然后在主题入口导入即可。这种方式不需要改动主题源码，升级时也不会产生额外冲突。
:root {
--vp-c-brand: #42b883;
--vp-c-brand-light: #5ecf9a;
--vp-font-family-base: 'Inter', 'PingFang SC', 'Microsoft YaHei', sans-serif;
}
如果默认主题的布局无法满足需求，可以覆盖默认主题的 Layout 插槽。例如在 .vitepress/theme/index.ts 中引入自定义 Layout 组件，把文档页的头部、左侧导航或页脚替换成自己的 Vue 组件。VitePress 默认主题暴露了多个插槽，包括 doc-before、doc-after、aside-top、aside-bottom 等，可以在不改动核心结构的情况下插入自定义内容。更彻底的做法是继承 Theme 并重写整个布局，适合需要完全定制视觉体系的团队。
除了样式，还有几项扩展配置值得一开始就打开。代码高亮由 Shiki 提供，默认已支持多种语言，无需额外配置。本地搜索可以在 themeConfig.search 中开启，它会生成离线搜索索引，适合中小型文档站。最后更新时间和上一页下一页按钮也可以通过 lastUpdated 和 docFooter 字段控制，这些细节能明显提升读者的使用体验。
三、构建优化与部署上线
构建时 VitePress 会读取 .vitepress/config.mts 中的 base 字段。如果项目部署在域名的根路径，例如 docs.ipipp.com，base 可以保持为斜杠 /；如果部署在 GitHub Pages 的项目页，地址里会带仓库名，此时必须把 base 改成 /仓库名/，否则构建产物中的资源路径会指向根目录，页面打开后直接出现 404。修改 base 后记得重新构建，开发环境下路径行为也可能不同。
npm run docs:build npm run docs:preview
使用 GitHub Actions 部署到 GitHub Pages 是常见的自动化方案。将下面的工作流文件放到 .github/workflows/deploy.yml，当 main 分支有推送时就会自动安装依赖、构建文档，并把生成的静态文件发布到 gh-pages 分支。需要注意文档目录是 docs，构建输出目录是 docs/.vitepress/dist，action 的 publish_dir 也要写成对应路径。
name: Deploy VitePress site
on:
push:
branches: [main]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run docs:build
- uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/.vitepress/dist
如果部署到自己的 Nginx 服务器，构建完成后把 docs/.vitepress/dist 目录下的内容上传到服务器，再配置一个静态站点即可。由于 VitePress 使用 history 路由模式，Nginx 需要设置 try_files 兜底到 index.html，这样刷新内页时不会返回 404。下面的配置中 root 指向实际静态文件目录。
server {
listen 80;
server_name docs.ipipp.com;
root /var/www/vitepress-dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}
部署后如果发现某些内部链接构建报错，可以检查 markdown.links 相关配置，或者将 ignoreDeadLinks 设为 true 跳过死链检查。生产环境建议开启 cleanUrls 或配置合适的 base，并配合 CDN 缓存静态资源。至此，一个结构清晰、可维护的 Vue 3 工程化文档站点就完成了从本地配置到线上部署的完整链路。