Git submodule 和 Monorepo 怎么选？各有什么优缺点？

Question

仓乃文 · Accepted Answer

Git submodule 和 Monorepo 是两种完全不同的代码组织方式，选错会导致团队协作效率大幅下降。核心区别在于：submodule 是多仓库的松耦合，Monorepo 是单仓库的紧耦合。选择取决于团队规模和项目耦合度。

对比分析：
```
| 维度           | Git Submodule          | Monorepo               |
|---------------|------------------------|------------------------|
| 代码位置       | 多个独立仓库            | 单一仓库               |
| 版本管理       | 各仓库独立版本          | 统一版本               |
| 代码共享       | 通过 submodule 引用     | 直接引用，无需发布      |
| 构建效率       | 各项目独立构建          | 可增量构建+缓存         |
| 团队协作       | 跨仓库 PR 繁琐         | 统一 PR，原子提交       |
| 权限控制       | 天然隔离               | 需要 CODEOWNERS        |
| 学习成本       | 低                     | 中                     |
| 适用场景       | 跨团队松耦合项目        | 同团队紧耦合项目        |
```

Submodule 常见坑：
```bash
# 1. 克隆时忘记 --recursive
git clone https://github.com/user/main-repo.git
cd main-repo
ls submodule-dir/  # 空的！

# 正确方式：
git clone --recursive https://github.com/user/main-repo.git
# 或克隆后补拉：
git submodule update --init --recursive

# 2. submodule 更新后主仓库状态不一致
cd submodule-dir
git pull origin main
cd ..
git status  # submodule 有变更，需要提交
git add submodule-dir
git commit -m "chore: update submodule"

# 3. 分支切换后 submodule 指向错误
git checkout feature
git submodule update  # 必须手动同步
```

Monorepo 推荐方案：
```
# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

# 优势：
# 1. 修改共享包后无需发布即可在项目中生效
# 2. 原子提交：一个 PR 同时修改多个包
# 3. 统一的 CI/CD 和代码规范
# 4. Turborepo 缓存加速构建
```

补充说明：
- Submodule 适合开源项目引用其他开源库，或跨公司合作
- Monorepo 适合同一团队维护的多个紧密关联的项目
- 混合方案：主仓库用 Monorepo，第三方依赖用 submodule
- Submodule 的 detached HEAD 问题经常让新手困惑，务必团队培训