VitePress

让文档“漂亮”起来的幕后功臣——VitePress

如果你最近打开过 vuejs.org，大概率会被它清爽、灵动、几乎“无刷新”的浏览体验吸引住：

• 页面切换像 SPA 一样丝滑
• 代码块自带语法高亮与行号
• 左侧导航、右侧大纲同时滚动定位
• 暗黑模式一键切换，配色依旧优雅

很多人以为是“Vue + 某个 UI 组件库”的功劳，其实真正撑起这份美感的，是 Vue 团队亲手打造的静态站点生成器——VitePress。今天，Kimi 就带你拆解这款“文档神器”到底厉害在哪。

---

一、VitePress 是什么？

一句话定义：

“基于 Vite 的静态网站生成器，专为技术文档而生。”

• 血统：Vue 官方亲儿子，隔壁老大哥 VuePress 的“次世代”版本
• 底层：用 Vite 替代 Webpack，开发启动速度提升 5～10 倍
• 输出：纯静态 HTML，SEO 友好，可部署在任意 CDN
• 主题：默认提供一套极简、响应式、深色模式友好的文档主题；同时支持深度自定义

---

二、为什么 Vue 官网看起来“格外漂亮”？

1. VitePress 的默认主题已足够简洁
   白底、蓝灰点缀、17 px 正文字号、精心调校的行高——信息密度与留白平衡得恰到好处。

2. Vue 团队做了三层定制

   • 色彩系统：在默认 CSS 变量基础上，植入品牌绿与渐变蓝，保证白天/夜晚双模式一致性
   • 交互组件：Hero 区域的手势动画、API 表格的折叠/展开、代码示例的“实时编辑”……全部是官网自己写的 SFC，直接丢进 docs/.vitepress/theme 即可
   • 路由动效：利用 VitePress 提供的 enhanceApp 钩子，注入页面切换过渡和滚动行为，让“静态站”有了 SPA 级体验

3. Vite 的“瞬时热更”让设计调参不再痛苦
   改一行色值，浏览器 200 ms 内刷新；设计师与开发者并肩作战，才能把像素级细节打磨到极致。

---

三、VitePress 的“隐藏技能”

功能	一句话亮点
Markdown 扩展	支持在 Markdown 里直接写 <script setup> 组件，文档即 demo
内置搜索	基于 FlexSearch 的离线全文搜索，0 配置、毫秒级响应
多语言	一行配置生成 /zh、/en 并行目录，切换语言不丢锚点
Git 集成	自动显示“编辑此页”链接、最近更新时间与贡献者头像
纯静态输出	vitepress build 直接吐出 HTML，丢到 Netlify、GitHub Pages、CDN 即可

---

四、5 分钟上手（Kimi 亲测）

1. 初始化

   pnpm create vitepress@latest docs-app
   cd docs-app
   pnpm install

2. 写文档
   把 .md 文件扔进 docs，路由自动生成；需要组件演示就写 .vue 文件，然后在 Markdown 里：

   <MyGlobalComponent/>

3. 美化
   在 docs/.vitepress/theme/index.ts 导入自定义组件或全局样式，VitePress 会自动合并默认主题。

4. 部署

   pnpm run docs:build
   # 把 docs/.vitepress/dist 推到 gh-pages 分支，收工！

---

五、总结

Vue 官网之所以“漂亮”，并不是用了哪个花哨的 UI 框架，而是用对了工具——VitePress 让“写文档”这件事回归 Markdown 的简洁，却又能随时插入 Vue 组件的灵活；加上 Vue 团队对像素级细节的执念，才呈现出我们看到的“丝滑 + 优雅”。

如果你也想让自己的项目文档“瞬间高级”，不妨直接试试 VitePress。
毕竟，漂亮的不是官网，而是选择 VitePress 的你。

kimi