跳到主要内容
版本：2.2.0

Docusaurus 迁移执行计划

项目信息​

  • 当前系统：Legacy GitBook (v3.x)
  • 目标系统：Docusaurus v3.x
  • 迁移时间：2026-03-16 开始
  • 负责人：AI 助手 + Elmo

迁移目标​

  1. 完整迁移现有 GitBook 文档到 Docusaurus
  2. 启用多版本支持
  3. 保持所有现有功能（搜索、图表、代码高亮）
  4. 实现自动化部署

执行计划​

阶段一：环境准备与项目初始化 (Day 1)​

  • 检查 Node.js 和 npm 环境
  • 创建 Docusaurus 项目
  • 安装必要依赖
  • 验证基础构建

阶段二：文档内容迁移 (Day 1-2)​

  • 迁移所有 Markdown 文档
  • 迁移图片和静态资源
  • 转换 SUMMARY.md 到 sidebars.js
  • 修复文档中的相对路径

阶段三：功能配置 (Day 2)​

  • 配置 Mermaid 图表支持
  • 配置本地搜索插件
  • 设置代码高亮主题
  • 配置导航栏和页脚

阶段四：多版本支持 (Day 2-3)​

  • 确定版本策略
  • 创建初始版本 (v1.0)
  • 配置版本切换器
  • 测试版本切换功能

阶段五：构建与测试 (Day 3)​

  • 本地构建测试
  • 功能完整性测试
  • 性能测试
  • 兼容性测试

阶段六：自动化部署 (Day 3-4)​

  • 编写部署脚本
  • 配置自动 Git 拉取
  • 设置构建触发器
  • 测试部署流程

阶段七：切换与验证 (Day 4)​

  • 备份原 GitBook 项目
  • 切换部署
  • 最终验证
  • 文档更新

详细步骤​

1. 项目初始化​

cd /Users/zhongqijun/Workspaces
npx create-docusaurus@latest aegis-docs classic
cd aegis-docs

2. 依赖安装​

npm install --save @docusaurus/theme-mermaid
npm install --save @cmfcmf/docusaurus-search-local

3. 目录结构转换​

需要将 GitBook 的目录结构转换为 Docusaurus 格式：

  • GitBook/content/ → aegis-docs/docs/
  • GitBook/assets/ → aegis-docs/static/img/
  • GitBook/SUMMARY.md → aegis-docs/sidebars.js

4. 配置文件​

主要配置文件：

  • docusaurus.config.js - 主配置文件
  • sidebars.js - 侧边栏导航
  • package.json - 依赖管理

风险与应对​

风险 1：路径引用问题​

  • 风险：文档中的图片和链接路径需要调整
  • 应对：编写脚本批量修复路径，手动检查关键文档

风险 2：插件兼容性问题​

  • 风险：GitBook 插件可能无法直接迁移
  • 应对：寻找 Docusaurus 的替代插件，或自定义实现

风险 3：构建性能问题​

  • 风险：文档量大时构建时间可能较长
  • 应对：优化构建配置，考虑增量构建策略

风险 4：部署中断​

  • 风险：迁移期间可能影响现有文档访问
  • 应对：并行运行新旧系统，验证无误后再切换

成功标准​

  1. 所有文档内容完整迁移
  2. 所有功能正常工作
  3. 构建时间在可接受范围内
  4. 部署流程自动化
  5. 用户访问体验无下降

进度跟踪​

  • 每日更新本计划文档
  • 记录遇到的问题和解决方案
  • 定期验证迁移质量

联系方式​

  • 问题反馈：通过当前会话
  • 紧急情况：直接沟通

最后更新：2026-03-16 16:04 状态：计划创建完成，准备开始执行