ZCF 文档站迁移实践：从 GitBook 到 VitePress 的多语言文档工程化改造

• 开发工具
• CLI
• AI 应用

本篇技术指南完整还原 ZCF（Zero-Config Code Flow）项目文档站由 GitBook 结构迁移至 VitePress 的全过程。ZCF 的官方文档此前采用 GitBook 多语言目录（SUMMARY.md）组织，迁移后已由 VitePress 接管为支持 en / zh-CN / ja-JP 三语、内置本地搜索、暗色模式与 GitHub Pages 自动部署的静态站点。阅读完本文，你将掌握 VitePress 多语言站点的骨架设计（locales、nav、sidebar）、基于导航定义批量生成侧边栏的工程化手法、UnoCSS 主题定制以及 GitHub Actions 部署流水线的完整落地方式，并可把同一套方案复用到自己的文档项目中。

迁移背景与目标

迁移计划记录于仓库 .zcf/plan/history/docs-vitepress-migration.md，核心背景与约束如下：

• 旧结构基于 GitBook：以多语言目录 +SUMMARY.md组织章节，每门语言一套文件树；
• 目标站点框架为 VitePress，配置模式参考 unocss/docs；
• 必须包含国际化：默认语言 en、主内容 zh-CN、ja-JP 为壳（占位）；
• 支持搜索、暗色模式、GitHub 链接；
• 部署方式复制 unocss 的 GitHub Pages 脚本（实际落地为.github/workflows/docs-deploy.yml）。

对应到当前仓库，迁移后的目录布局为：

docs/ ├── .vitepress/ # VitePress 核心配置与主题 │ ├── config.ts │ └── theme/ ├── CNAME # 自定义域名 ├── index.md # 根入口，跳转 /en/ ├── package.json # docs 包脚本与依赖 ├── uno.config.ts # UnoCSS 配置 ├── tsconfig.json ├── en/ # 英文（默认语言） ├── zh-CN/ # 简体中文（主内容） ├── ja-JP/ # 日语（壳） └── public/assets/ # favicon 等静态资源

迁移执行的六个阶段

原计划将整个迁移拆成六个可独立验证的步骤，当前仓库均已落地（计划文档中以 ✅ 标记完成）：

1. 整理 GitBook 导航：读取docs/{en,zh-CN,ja-JP}/SUMMARY.md，抽取章节结构，记录成导航映射；
2. 分析 unocss 配置：阅读 unocss/docs 的config、vite.config.ts等，列出需要复制的模块与依赖；
3. 初始化 VitePress 目录：在docs/.vitepress/下创建config.ts及相关 theme、locale 配置；
4. 迁移导航与内容：将导航映射到 VitePress 的locales、nav、sidebar，保证 zh-CN 完整、en/ja-JP 占位；
5. 部署脚本同步：新增 GitHub Pages 工作流.github/workflows/docs-deploy.yml，以pnpm docs:build产出静态站点并部署；
6. 验证：运行pnpm docs:build构建通过。

下面按阶段深入拆解每一环的落地细节与源码实现。

阶段一：导航结构与 SUMMARY 解析

GitBook 时代的信息架构沉淀在三份语言各自的SUMMARY.md中，例如 docs/en/SUMMARY.md 将文档划分为七个章节：Getting Started、Features、Advanced Guides、CLI Commands、Workflow Details、Best Practices、Development Documentation。zh-CN 与 ja-JP 目录下存在结构等价、标题翻译不同的同构文件。

这份章节映射正是 VitePresssidebar的天然输入。迁移的关键在于把"SUMMARY 式"的平铺目录，重写为 VitePress 面向路由前缀（/en/、/zh-CN/、/ja-JP/）的侧边栏数据结构，同时把每篇 Markdown 的相对链接（例如getting-started/installation.md）换算为以语言前缀开头的路由路径。

阶段二与三：VitePress 目录初始化与依赖装配

迁移后的文档站是一个独立的 pnpm workspace 子包，见 docs/package.json：

{ "name": "@zcf/docs", "type": "module", "private": true, "scripts": { "dev": "vitepress dev --port 3366", "build": "vitepress build", "preview": "vitepress preview" }, "dependencies": { "@iconify-json/carbon": "catalog:docs", "@unocss/reset": "catalog:docs", "unocss": "catalog:docs", "vitepress": "catalog:docs", "vue": "catalog:docs" } }

几个值得注意的工程细节：

• 固定开发端口：vitepress dev --port 3366将本地开发服务固定到 3366 端口，避免多人开发时端口冲突；
• 依赖走 workspace catalog：catalog:docs说明版本统一收敛在根 pnpm-workspace.yaml 的 catalog 中，文档站与 CLI 主体共享版本管理策略；
• 依赖组合：vitepress+vue+unocss+@unocss/reset+@iconify-json/carbon（图标集，供主题内i-carbon-close之类的图标类使用）构成站点运行时底座。

VitePress 需要一个 TypeScript 工程来支撑.vitepress下的源码，docs/tsconfig.json 采用moduleResolution: "bundler"、noEmit: true，并将include指向.vitepress/**/*与页面源码，保证config.ts与 Vue 组件在编辑器内获得完整类型检查。

阶段三核心：多语言配置与侧边栏生成器

站点中枢是 docs/.vitepress/config.ts，它以defineConfig声明了站点标题、描述、srcDir: '.'、lang: 'en-US'、lastUpdated与cleanUrls: true，并通过head注入 favicon：

export default defineConfig({ title: siteTitle, description: siteDescription, srcDir: '.', lang: 'en-US', lastUpdated: true, cleanUrls: true, head: [ ['link', { rel: 'icon', type: 'image/x-icon', href: '/assets/favicon.ico' }], ], vite: { plugins: [UnoCSS()], }, // ... })

createSidebar：把章节定义批量转成侧边栏

为避免手工维护上百条侧边栏项，config.ts 定义了一个createSidebar工厂函数（对应源码 docs/.vitepress/config.ts#L19-L42）：

function createSidebar(definition: SidebarDefinitionSection[], base: string): DefaultTheme.SidebarItem[] { const normalizedBase = base.endsWith('/') ? base : `${base}/` return definition.map(section => ({ text: section.text, collapsed: false, items: section.items.map((item) => { let link = item.link if (!link) { link = normalizedBase } else if (link === 'index') { link = normalizedBase } else if (!link.startsWith('/')) { link = `${normalizedBase}${link}` } return { text: item.text, link } }), })) }

它的核心价值在于路径归一化：

• 空链接与'index'都指向语言根（如/zh-CN/），天然兼容xxx/index.md这类目录入口；
• 未以/开头的相对链接自动拼接语言前缀（如getting-started/installation→/zh-CN/getting-started/installation）；
• 以/开头的绝对链接原样保留，允许跨语言引用。

这意味着三份侧边栏只需描述"章节 → 条目 → 短链接"的数据，路径细节全部由工厂统一计算，迁移后若要调整目录结构，只需改一处定义。

三语侧边栏与 locales 体系

config.ts 中依次构建了zhSidebar、enSidebar、jaSidebar三份数据，分别以/zh-CN、/en、/ja-JP为 base。以 zh-CN 为例，其章节覆盖"项目介绍 / 开始使用 / 功能特性 / 进阶指南 / CLI 命令 / 工作流详解 / 最佳实践 / 开发文档"八大区块（源码 docs/.vitepress/config.ts#L44-L126），且与 en / ja-JP 保持条目级一一对应——这正是"en 默认、zh-CN 主内容、ja-JP 壳"结构的导航载体。

顶级themeConfig与locales分工如下：

• themeConfig.search.provider = 'local'：启用 VitePress 内置本地全文搜索，无需外部搜索服务，离线即可构建（源码 docs/.vitepress/config.ts#L314-L316）；
• socialLinks与editLink：提供 GitHub 仓库链接与"Edit this page on GitHub"编辑入口，满足计划中"GitHub 链接"的硬性要求；
• nav在每个 locale 内分别定义（如 en 的 Home / Getting Started / Features / CLI / Workflows / Best Practices），并随语言切换而本地化；
• 每个 locale 配置自己的sidebar、footer文案与editLink文本（zh-CN 为"在 GitHub 上编辑此页"，ja-JP 为"GitHubでこのページを編集"）。

根入口 docs/index.md 使用layout: home配合useRouter().go('/en/')在挂载后重定向到英文默认首页，实现"默认 en"的语言兜底。

阶段三延伸：UnoCSS 主题定制

站点主题位于 docs/.vitepress/theme/index.ts，它继承 VitePress 默认主题并注入自定义布局：

import 'uno.css' import '@unocss/reset/tailwind.css' import './custom.css' export default { extends: DefaultTheme, Layout: () => { return h(DefaultTheme.Layout, null, { 'layout-top': () => h(TopBanner), }) }, } satisfies Theme

要点：

• UnoCSS 原子化样式：import 'uno.css'引入 UnoCSS 运行时产物，配合根级 docs/uno.config.ts 的三个预设presetWind3()（Wind3 工具类）、presetAttributify()（属性化写法）、presetIcons()（图标类），Markdown 与 Vue 组件内可直接使用fixed top-0 z-200等原子类与i-carbon-close图标类；
• 布局插槽扩展：通过 VitePress 布局插槽'layout-top'在页面顶部挂载 TopBanner.vue，实现一个可关闭、按语言切换内容的顶部推广横幅；组件借助useData().lang响应式读取当前语言，并为zh-CN / en / ja-JP分别维护文案映射，关闭时通过document.documentElement.classList增减has-top-banner以联动custom.css中的页面偏移样式。

暗色模式由 VitePress 默认主题原生提供（跟随系统或手动切换），custom.css中针对明暗双态补充了定制样式，无需额外依赖。

阶段五：GitHub Pages 部署流水线

部署部分完全对齐"复制 unocss 的 GitHub Pages 脚本"的目标，落地为 .github/workflows/docs-deploy.yml。工作流在main分支 push 时触发（同时支持workflow_dispatch手动触发），采用build + deploy 双 Job结构：

permissions: contents: read pages: write id-token: write concurrency: group: docs-deploy cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 - uses: actions/setup-node@v4 with: cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm -F @zcf/docs build # 构建 docs 子包 - uses: actions/upload-pages-artifact@v3 with: path: docs/.vitepress/dist deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages steps: - uses: actions/deploy-pages@v4

工程化细节包括：

• 工作区过滤构建：pnpm -F @zcf/docs build只构建 docs 子包，避免在文档发布时编译整个 CLI 工程；
• 锁文件保证可复现：pnpm install --frozen-lockfile严格按 pnpm-lock.yaml 安装，杜绝 CI 与本地依赖漂移；
• Pages 权限模型：pages: write+id-token: write是 GitHub Actions 原生 Pages 部署（deploy-pages）的必要权限组合；
• 并发保护：concurrency.group: docs-deploy保证同一时间只有一个文档发布任务，cancel-in-progress: true使新推送自动取消排队中的旧构建；
• 产物路径：上传docs/.vitepress/dist，即 VitePress 的默认构建输出目录。

配套的 docs/CNAME 内容为zcf.ufomiao.com，为 GitHub Pages 站点绑定自定义域名。仓库同时保留 .github/workflows/ci.yml 与 .github/workflows/release.yml，分别承担主工程 CI 与发布任务，与文档部署互不干扰。

阶段六：本地构建与验证

验证迁移是否成功，只需在仓库根目录执行：

# 本地开发（固定 3366 端口） pnpm -F @zcf/docs dev # 生产构建，输出到 docs/.vitepress/dist pnpm -F @zcf/docs build # 本地预览构建产物 pnpm -F @zcf/docs preview

计划文档中明确以pnpm docs:build构建通过作为阶段六的完成判据；在当前仓库中，该命令等价于通过 workspace filter 执行@zcf/docs包的build脚本。构建通过即意味着：

• 三份语言侧边栏定义与全部 Markdown 路径均能解析，不存在死链路由；
• locales配置通过 VitePress 的 locale 校验；
• UnoCSS 与主题组件编译无类型错误（受 docs/tsconfig.json 严格模式约束）。

迁移方案要点总结

回顾这次 GitBook → VitePress 迁移，可以提炼出几条可复用的经验：

1. 以数据驱动导航：createSidebar(definition, base)把"目录结构"降维成纯数据，语言前缀拼接逻辑收敛在工厂内，是本次多语言站点最关键的抽象；
2. 三语同构、一主两壳：en / zh-CN / ja-JP 三份 sidebar 条目完全对齐，zh-CN 承载完整内容，ja-JP 保持占位，保证了未来补全翻译时不会破坏导航结构；
3. 本地搜索优先：search.provider: 'local'让全文搜索随构建产物一起离线可用，省去外部搜索索引服务；
4. 原子化样式与主题定制解耦：UnoCSS 负责工具类与图标，VitePress 布局插槽负责扩展点，TopBanner通过useData().lang响应式做多语言内容分发；
5. 部署流水线独立化：文档发布作为独立子包构建 + GitHub Pages 原生部署，与主工程 CI/发布流程解耦，--frozen-lockfile与并发组保证发布可复现、不堆积。

相关实现文件一览：多语言配置与侧边栏生成器见 docs/.vitepress/config.ts，主题扩展见 docs/.vitepress/theme/index.ts，部署流水线见 .github/workflows/docs-deploy.yml，迁移执行记录见 .zcf/plan/history/docs-vitepress-migration.md。

• 开发工具
• CLI
• AI 应用