Monorepo 介绍

[TOC]

**Monorepo** 是“单一代码仓库”（Monolithic Repository）的缩写，指**在一个版本控制仓库（如一个 Git 仓库）中存放多个相互独立但又可能相互依赖的项目（如服务、库、前端应用等）**。

与之相对的是 **Multirepo**（多仓库模式）：每个项目都有自己的独立仓库。

下面我从基础到深入，帮你完整理解 Monorepo 并给出学习路径。

## 1. 为什么要用 Monorepo？一个简单例子

假设你正在开发三个项目：
- `shared-ui`（公共 UI 组件库）
- `admin-app`（后台管理系统）
- `user-app`（用户端网站）

在 **Multirepo** 下：
- 三个仓库互不相通。
- 你在 `shared-ui` 修复一个 bug，需要在 `admin-app` 和 `user-app` 中分别更新依赖版本、重新安装、测试、发布。

在 **Monorepo** 下：
- 所有代码都在同一个 Git 仓库中。
- 你可以一次性修改 `shared-ui` 和 `admin-app`，并立即在同一个构建流程中验证它们的兼容性。
- 提交一次变更，CI 可以自动构建和测试所有受影响的项目。

## 2. Monorepo 的优点
为什么大厂和现代工具都在用？

| 优点 | 说明 |
|------|------|
| **代码共享方便** | 多个项目可以直接引用本地其他模块的源码，无需发布到 npm。 |
| **统一依赖管理** | 顶层可以管理共用的依赖版本，避免多个项目依赖不一致。 |
| **原子提交** | 一次 commit 可以同时修改多个项目的代码，并保证它们的一致性。 |
| **简化 CI/CD** | 可以只构建和测试发生变更的项目（借助工具），避免重复工作。 |
| **重构更容易** | 跨项目的重命名、API 改动可以一次性完成。 |
| **统一的工具配置** | ESLint、Prettier、TypeScript、Jest 等可以共享一套配置。 |

## 3. Monorepo 的缺点
不是银弹

| 缺点 | 说明 |
|------|------|
| **仓库体积变大** | 所有代码在一个仓库，clone 和 fetch 可能变慢（可通过 sparse checkout 缓解）。 |
| **权限管理复杂** | 很难精确控制不同团队对不同子目录的写权限（Git 原生不支持目录级权限）。 |
| **工具链要求高** | 需要专门的 Monorepo 管理工具（如 Nx、Turborepo、Lerna、pnpm workspace）来优化构建和任务编排。 |
| **CI 设计更复杂** | 需要检测变更范围，避免每次全量构建。 |

## 4. 常见的 Monorepo 管理工具

| 工具 | 特点 | 适用场景 |
|------|------|----------|
| **pnpm workspace** | 基于符号链接的软连接方式，依赖管理速度快，节省磁盘空间 | 中小型项目，或想要极简体验 |
| **Yarn Workspaces** | 流行的 workspace 方案，配合插件（如 `@yarnpkg/plugin-version`）使用 | 通用 |
| **Nx** | 功能强大的构建系统，支持增量构建、计算缓存、依赖图可视化 | 大型项目，需要精细的构建优化 |
| **Turborepo** | 由 Vercel 出品，类似 Nx 但更轻量，专注于任务编排和缓存 | 中等规模以上的项目 |
| **Lerna** | 早期流行的 Monorepo 工具，现在通常与 Yarn Workspaces 或 pnpm 配合 | 发布 npm 包场景 |
| **Rush** | 微软出品，适合大型企业，策略严格 | 超大型团队 |

## 5. Monorepo 的核心工作模式

一个典型的 Monorepo 目录结构：

```BASH
my-monorepo/
├── package.json            # 根配置，定义 workspaces
├── pnpm-workspace.yaml     # pnpm workspace 声明
├── apps/                   # 应用（可直接运行的项目）
│   ├── admin-app/
│   └── user-app/
├── packages/               # 共享包（库）
│   ├── shared-ui/
│   └── utils/
└── tooling/                # 工具配置
    └── eslint-config/
```

**关键操作**：
- 安装依赖：在根目录执行 `pnpm install`，所有子项目的依赖都会提升到根 `node_modules`（但保持隔离）。
- 运行脚本：通过 `pnpm run --filter <package> build` 仅构建某个项目。
- 发布包：工具（如 changesets）可以自动检测变更并批量发布。

## 6. 学习 Monorepo 的最佳路径

### 第一步：理解核心概念
- 阅读 [Monorepo 是什么？](https://semaphoreci.com/blog/what-is-monorepo)（英文）或搜索中文文章。
- 看 [pnpm workspace 文档](https://pnpm.io/workspaces)（最易上手）。

### 第二步：动手搭建一个最小示例
```bash
mkdir my-first-monorepo && cd my-first-monorepo
pnpm init
mkdir packages
cd packages
mkdir math-utils && cd math-utils
pnpm init
# 编写 index.ts，导出 add 函数
cd ../..
mkdir app
cd app
pnpm init
# 在 app/package.json 中添加依赖: "math-utils": "workspace:*"
# 然后在 app 中引用 math-utils
pnpm install
```
**实践目标**：让 app 成功调用 math-utils 的函数。

### 第三步：学习使用一种 Monorepo 工具
推荐顺序：
1. **pnpm workspace**（最轻量）
2. **Turborepo**（构建缓存强大）
3. **Nx**（全面但略重）

### 第四步：理解依赖图与任务编排
- 学会使用 `pnpm list --depth=-1 --filter ...` 查看依赖关系。
- 使用 Turborepo 的 `turbo run build` 观察增量构建。

### 第五步：结合 CI 实践
- 配置 GitHub Actions 或 GitLab CI，实现仅构建和测试变更的项目。
- 工具：`changesets`（版本管理与发布）。

## 7. 常见问题与误区

| 问题 | 解答 |
|------|------|
| Monorepo 等于大仓库吗？ | 不，它强调的是**结构化的单一仓库**，而非所有代码乱放。 |
| 小项目需要 Monorepo 吗？ | 通常不需要。当你有 ≥2 个互相依赖的项目时，才考虑。 |
| Monorepo 一定要用特定工具吗？ | 如果只有两个项目，手动管理符号链接也可以。但为了可扩展性，推荐工具。 |
| 和微服务的关系？ | 微服务可以用 Monorepo 管理多个服务的代码，也可以用 Multirepo，两者不冲突。 |

## 8. 继续深入学习资源

- **官方文档**：[pnpm Workspaces](https://pnpm.io/workspaces) | [Turborepo](https://turbo.build/repo/docs) | [Nx](https://nx.dev/getting-started/intro)
- **视频**：YouTube 搜索 “Monorepo tutorial pnpm”
- **实战项目**：找一个使用 Monorepo 的开源项目，例如 [Vite](https://github.com/vitejs/vite) 自身（它用 pnpm workspace 管理核心、插件、playground 等）