部署 VitePress 文档
Vue 驱动文档 SSG，.vitepress/dist 部署到任何静态主机。
平台入门
为什么
VitePress 由 Vite + Vue 驱动，生成快速文档站，内置搜索、暗色模式和 i18n。是 VuePress 继任者，开发服务器快 10 倍。
平台即服务采用率 2024 年增长 24%，团队从虚拟机管理转向 git push 部署。the cloud infrastructure market reached $330B in 2024, growing 22% year-over-year (Synergy Research)，PaaS 层捕获了大多数新工作负载。
何时使用
项目文档、API 参考和知识库用 VitePress。非文档站点避免 — 用 Astro/Vue。
如何做
1. 构建 — vitepress build docs 输出 docs/.vitepress/dist
2. 部署 — 上传 dist/ 到 Vercel/Netlify/GitHub Pages
3. 配置 — .vitepress/config.ts 配主题、导航、侧边栏
4. 搜索 — 内置本地搜索，大文档用 algolia
5. Base — 子路径部署在配置设 base
示例
// docs/.vitepress/config.ts
import { defineConfig } from "vitepress";
export default defineConfig({
title: "My Docs",
base: "/docs/",
themeConfig: { nav: [{ text: "Home", link: "/" }] },
});
// 部署：vitepress build docs && npx wrangler pages deploy docs/.vitepress/dist
常见问题
- ⚠Base 路径错误 — 子路径部署资源 404，配置设 base
- ⚠搜索不工作 — 本地搜索需构建，或配 algolia appId/key
- ⚠环境间配置漂移 — 使用基础设施即代码（Terraform/Pulumi）保持 dev/staging/prod 一致
最佳实践
- ✓小文档用内置本地搜索 — 无外部依赖，即时
- ✓配置中组织侧边栏 — 所有页面一致导航
- ✓设置健康检查和优雅关闭 — 处理 SIGTERM 以在退出前排空进行中的请求