ADR-001：采用 Monorepo 管理前端代码库
状态
已采纳（Adopted）
背景
公司目前有 8 条业务线，每条业务线都有自己的前端仓库（Polyrepo）。随着业务发展，出现以下问题：
- 相同组件（Button、Table、Form）在多个仓库重复开发，复用率低。
- 组件库版本管理混乱，不同业务线引用的组件库版本不一致。
- 跨仓库调试和联调成本高，一个问题可能涉及多个仓库修改。
- CI/CD 配置分散，维护成本高。
决策目标
- 提高组件和工具函数的复用率。
- 统一技术栈和工程化配置。
- 降低跨业务线协作成本。
- 支持独立发布和灰度更新。
备选方案
方案 1：保持 Polyrepo
- 优点：仓库独立，权限管理简单，构建速度快。
- 缺点：复用困难，版本管理混乱，协作成本高。
方案 2：采用 Monorepo（pnpm workspace + Turborepo）
- 优点：便于复用、统一构建、统一 CI/CD、支持跨包重构。
- 缺点：仓库体积大，需要学习 Monorepo 工具链，权限管理稍复杂。
方案 3：Git Submodules
- 优点：保留独立仓库，又能引用共享代码。
- 缺点：管理复杂，容易出现版本不一致，体验不如 Monorepo。
决策
采用 方案 2：Monorepo（pnpm workspace + Turborepo）。
权衡（Trade-off）
| 维度 | 影响 | 说明 |
|---|---|---|
| 复用性 | ✅ 显著提升 | 共享组件库、工具函数、类型定义 |
| 协作成本 | ✅ 降低 | 一个 PR 可以修改多个相关包 |
| 构建复杂度 | ⚠️ 增加 | 需要 Turborepo 管理依赖图和缓存 |
| 权限管理 | ⚠️ 需要适配 | 使用 CODEOWNERS 控制各包负责人 |
| 学习成本 | ⚠️ 中 | 团队需要学习 pnpm workspace 和 Changesets |
实施计划
- 第 1 周：搭建 Monorepo 基础结构，迁移共享组件库。
- 第 2-4 周：逐步迁移各业务线应用。
- 第 5 周：接入 Turborepo 远程缓存和 Changesets 版本管理。
- 第 6 周：灰度切换，验证 CI/CD 流水线。
相关决策
- ADR-002：组件库版本管理采用 Changesets
- ADR-003：CI/CD 采用 GitHub Actions + Turborepo
决策人
- 前端架构师：张三
- 技术总监：李四
日期
2026-03-10
最后更新
2026-06-24