FuelLabs/fuels-ts项目API文档部署策略优化

在FuelLabs/fuels-ts项目中，文档系统采用了双版本机制：稳定版(stable)和每日构建版(nightly)。然而，当前API文档的部署方式存在一个关键问题——当主分支(master)合并新代码并重新部署应用时，可能会破坏稳定版文档中的链接。

当前问题分析

现有部署模式中，文档系统与API文档的版本控制存在不一致性：

• 每日构建版(nightly)：

  • 文档：基于最新合并代码
  • API文档：基于最新合并代码

• 稳定版(stable)：

  • 文档：基于发布版本
  • API文档：却基于最新合并代码（这是不正确的）

这种不一致性导致稳定版文档可能引用到不兼容的API文档内容，造成用户体验问题。

解决方案设计

经过技术团队讨论，制定了以下优化方案：

1. Vercel环境配置：

   • 创建两个独立部署环境
   • 每日构建环境(nightly)：每次主分支合并时自动更新
   • 生产环境(production)：仅在有稳定版本发布时更新

2. 文档链接动态替换机制：

   • 使用占位符(如DOCS_API_URL)替代硬编码链接
   • 根据使用场景动态替换：
     • 本地开发：指向本地API文档服务
     • PR预览：将API文档输出到/docs/dist/api目录，与主文档一起部署
     • 稳定版文档：指向生产环境API文档
     • 每日构建版文档：指向每日构建环境API文档

3. 链接检查优化：

   • 为CI/CD流程中的链接检查器提供本地服务
   • 解决新API链接在合并前导致检查失败的问题

技术实现要点

1. 环境隔离：

   • 确保两个部署环境完全独立
   • 生产环境禁用分支自动跟踪，仅手动更新

2. 发布流程调整：

   • 修改稳定版发布工作流
   • 包含API文档的同步更新步骤

3. 文档构建优化：

   • 在Vitepress配置中添加API文档输出处理
   • 实现开发环境与生产环境的无缝切换

预期收益

这一优化将带来以下好处：

1. 版本一致性：稳定版文档与API文档保持严格版本对应关系
2. 开发体验提升：本地开发与CI流程更加顺畅
3. 维护便利性：统一的链接管理机制降低维护成本
4. 用户体验改善：消除因版本不一致导致的链接失效问题

通过这套方案，FuelLabs/fuels-ts项目的文档系统将实现更加可靠和一致的版本控制，为开发者提供更好的使用体验。