VitePress 站点初始化、主题与部署治理手册
VitePress 适合以 Markdown 为主、需要 Vue 增强和快速开发反馈的技术站点。内容源、站点配置、默认主题与 Vite 插件共同进入构建；开发服务器成功只能证明本地按需渲染可用，不能替代静态构建和真实 base 路径验证。
初始化项目并固定运行时
安装或初始化使用项目本地依赖，提交锁文件并固定 Node 支持线。脚手架生成的目录只是起点，团队还要确定内容根、配置位置、输出目录和部署前缀。
npm add -D vitepress
npx vitepress init
npm run docs:dev
npm run docs:build依赖安装与构建命令进入 package scripts，CI 使用干净安装。全局命令只适合个人试用，不应成为唯一发布入口。
内容源和主题各自负责
Markdown 保存页面事实，frontmatter 提供标题、导航或页面行为，主题配置组织导航、侧栏、搜索和布局。Vue 组件可以增强页面，但会扩大客户端运行时和安全边界。普通 Markdown 与 Mermaid 的语法和渲染权威说明分别回到家族 19 的 Markdown 与 Mermaid。
import {defineConfig} from 'vitepress'
export default defineConfig({
base: '/handbook/',
cleanUrls: true,
themeConfig: {nav: [{text: '首页', link: '/'}]},
})配置影响需要用 URL、生成目录和浏览器行为验证，不能只看对象能被 TypeScript 解析。
SSR 与客户端增强的边界
构建阶段会在 Node 环境执行 SSR，直接访问 window、document 或浏览器存储会失败。浏览器专属逻辑放到挂载阶段或客户端组件中，并为无 JavaScript 环境保留可读内容。插件和主题拥有读取正文与环境的能力，进入供应链审计范围。
正向验证包含纯 Markdown、一个受控 Vue 组件、静态资源和站内链接。构建后检查 HTML 中有主体内容，浏览器加载无 hydration 错误。反例在顶层读取 window，预期生产构建明确失败。
路由、资源和部署前缀
文件路径、clean URL、base 和托管平台重写共同决定最终地址。public 资源以站点根语义引用，模块资源由 Vite 处理并可能带哈希。子路径部署必须在真实前缀下检查首页、深链接、图片和刷新行为。
源页面 docs/guide/start.md
站点 base /handbook/
部署 URL /handbook/guide/start.html 或 clean URL404 先区分文件不存在、base 错误、重写缺失和大小写差异。旧 URL 通过重定向保留，不用删除页面后依赖搜索引擎自愈。
搜索、构建和发布证据
本地搜索索引应只包含可发布页面，服务端搜索还要处理权限与删除。项目接入 CI 后按顺序执行内容检查、链接检查、静态构建和关键页面 smoke，制品记录来源提交。发布身份只能写托管目标，预览构建不获得生产凭证。
失败时保留构建日志、路由清单、输出摘要和关键页面响应。缓存以锁文件和配置为键，主题或 base 变化时主动失效。容量治理关注页面数量、索引大小、客户端 JavaScript 和构建时间。
清理、回滚与迁移
清理插件前先查询 Markdown 容器、组件和配置引用；删除页面前处理导航、搜索和旧路由。回滚必须恢复内容、配置、锁文件和制品的一致组合。迁移到其他框架时先保留 Markdown、资源、frontmatter 字段含义和 URL 映射，再处理 Vue 专属组件。
长期 owner 分别维护内容契约、主题和发布平台。VitePress 的价值是轻量确定性构建，不是把每个页面扩成小型 Vue 应用。能从干净检出重建、在真实前缀访问并安全退出，才是站点工程完成。