Monorepo 全面指南
1. 什么是 Monorepo
Monorepo（单一仓库）是一种架构模式，将多个相关项目（如前端、后端、共享库等）放在同一个 Git 仓库中管理。
核心特点
- 代码共享：轻松共享类型定义、工具配置、UI 组件库等，避免复制粘贴。
- 统一依赖管理：使用 workspace 功能统一管理第三方依赖版本，减少版本冲突。
- 原子性提交：跨项目的更改（例如修改一个 API 并更新所有消费者）可以在一次 Git 提交中完成，保证代码状态的一致性。
- 统一 CI/CD：可以在一个流水线中处理所有项目，简化运维流程。
2. 主流 Monorepo 工具详解
第一梯队：现代化构建系统
Turborepo
由 Vercel 开发的高性能构建系统，专为构建性能优化而生。
- 核心优势：
- 智能缓存：支持本地和远程缓存（可与 Vercel 集成），只构建变化的部分（增量构建）。
- 任务调度：能够并行执行任务，极大缩短构建时间。
- 易用性：配置简单，学习曲线平缓，适合中大型项目，特别是 Next.js 生态。
- 缺点：功能相对单一（主要是构建），缺少代码生成器，插件生态相对较新。
Nx
由 Nrwl 开发的企业级全能 Monorepo 工具。
- 核心优势：
- 全功能工具链：提供代码生成器、丰富的插件生态（React, Angular, Node.js 等）。
- 可视化分析：拥有强大的依赖图分析和可视化工具，智能识别受影响的项目（Affected commands）。
- 缓存能力：同样支持本地和远程计算缓存。
- 缺点：学习曲线较陡峭，配置复杂，对项目结构有较强约束。
第二梯队：包管理器原生方案
pnpm Workspaces
目前最受欢迎的轻量级方案。
- 核心优势：
- 极致效率：通过硬链接共享依赖，磁盘空间效率极高，安装速度最快。
- 严格管理：避免“幽灵依赖”问题，确保依赖关系的准确性。
- 低成本：配置简单，内置于包管理器中。
- 缺点：缺少高级构建优化（缓存、并行构建），通常需要配合 Turborepo 使用。
Yarn Workspaces / npm Workspaces
- Yarn：原生支持 Monorepo，依赖提升（hoisting）机制成熟，支持零安装模式（PnP）。
- npm (7+)：无需额外工具即可实现基础 Monorepo，适合不想引入额外工具的简单项目。
第三梯队：特定场景与传统工具
Lerna
JS Monorepo 的鼻祖，现由 Nx 团队接管维护。
- 定位：专注于包版本管理和发布。
- 现状：虽然构建性能一般，但在发布多个 npm 包（Versioning & Publishing）方面依然是主流选择。它常与 Yarn/npm Workspaces 配合使用。
Rush (Microsoft) & Bazel (Google)
- Rush：为超大型企业项目（数百个包）设计，提供严格的依赖策略和详细的构建日志。
- Bazel：支持多语言（不仅限于 JS），追求极致的构建性能和缓存，但配置极其复杂，学习成本很高。
3. 全维度工具对比
| 工具 | 学习曲线 | 构建速度 | 缓存能力 | 包管理 | 代码生成 | 多框架支持 | 适合规模 | 核心简评 |
|---|---|---|---|---|---|---|---|---|
| pnpm | 低 | ⭐⭐⭐⭐ | ❌ | ✅ | ❌ | ✅ | 小-中型 | 磁盘最省，安装最快 |
| Turborepo | 低 | ⭐⭐⭐⭐⭐ | 远程+本地 | 依赖其他 | ❌ | ✅ | 中-大型 | 构建最快，配置最简 |
| Nx | 中-高 | ⭐⭐⭐⭐⭐ | 远程+本地 | 依赖其他 | ✅ | ✅ | 大型企业 | 功能最全，可视化强 |
| Lerna | 低 | ⭐⭐⭐ | ❌ | 依赖其他 | ❌ | ✅ | 小-中型 | 发包首选，老牌稳定 |
| Yarn | 低 | ⭐⭐⭐⭐ | ❌ | ✅ | ❌ | ✅ | 小-中型 | 生态兼容好 |
| Rush | 高 | ⭐⭐⭐⭐ | 本地 | ✅ | ❌ | ✅ | 超大型 | 微软方案，策略严格 |
| Bazel | 很高 | ⭐⭐⭐⭐⭐ | 远程+本地 | ✅ | ❌ | ✅ (多语言) | 超大型 | 谷歌方案，多语言支持 |
4. 最佳实践与组合建议
在实际开发中，往往不是单一工具的选择，而是“组合拳”。
推荐组合
pnpm + Turborepo (⭐ 最推荐)
- 适用场景：绝大多数现代 Web 应用开发。
- 理由：利用 pnpm 解决依赖安装速度和磁盘占用问题，利用 Turborepo 解决任务调度和构建缓存问题。这是目前性价比最高的方案。
pnpm + Nx
- 适用场景：需要标准化开发流程的大型团队。
- 理由：pnpm 处理底层依赖，Nx 提供上层的工作流约束、代码生成和深度依赖分析。
Yarn + Lerna
- 适用场景：开源组件库维护。
- 理由：传统的开源项目标准配置，重点在于 Lerna 强大的版本控制（Version）和发布（Publish）命令。
Vercel 生态全家桶 (Yarn/npm + Turborepo)
- 适用场景：深度绑定 Next.js 和 Vercel 部署平台的项目。
选型决策树
- 是简单的几个包共享代码？ →
pnpm Workspaces - 需要极速构建和 CI/CD 优化？ →
pnpm + Turborepo - 是复杂的企业级应用，需要统一规范？ →
Nx - 主要是为了发 npm 包？ →
Lerna - 是涉及多语言（Go, Java, TS）的巨型仓库？ →
Bazel