用 Git 管理多个项目时，你有没有遇到过这种场景：
一个前端项目引用了三个公共组件库，每个组件库都是独立的 Git 仓库。你不想把组件代码复制过来（升级麻烦），也不想每次构建前手动拉取（效率低）。
这时候 Git Submodule 就派上用场了。
但说实话，Submodule 是 Git 里最容易让人困惑的功能之一。命令多、行为反直觉、团队协同容易出问题。
今天把 Submodule 彻底讲清楚。
Submodule 是什么？
简单说，Submodule 就是"仓库里的仓库"。你的主项目可以引用其他 Git 仓库的特定提交，而不是复制代码。
好处很明显：
- 子模块保持独立版本控制
- 更新子模块只需改一个 commit hash
- 多个项目可以共享同一个子模块
添加 Submodule
基本用法
# 进入你的项目目录
cd my-project
# 添加子模块
git submodule add https://github.com/example/shared-components.git libs/components
这会在项目根目录创建 .gitmodules 文件：
[submodule "libs/components"]
path = libs/components
url = https://github.com/example/shared-components.git
同时会创建一个 libs/components/ 目录，里面是克隆的子模块代码。
指定分支
默认会克隆子模块的默认分支。如果你想指定分支：
git submodule add -b v2 https://github.com/example/shared-components.git libs/components
指定具体提交
生产环境建议锁定具体 commit，避免上游意外更新导致你的项目崩溃：
# 先克隆子模块
git submodule add https://github.com/example/shared-components.git libs/components
# 切换到想要的提交
cd libs/components
git checkout a1b2c3d
# 回到主项目
cd ../..
git add libs/components .gitmodules
git commit -m "fix: 锁定子模块到特定提交"
克隆含 Submodule 的项目
这是最容易踩坑的地方。只执行 git clone 是不够的。
# 错误做法：子模块目录是空的
git clone https://github.com/example/my-project.git
# 正确做法：一次性克隆并初始化所有子模块
git clone --recurse-submodules https://github.com/example/my-project.git
# 如果已经克隆了，再初始化
git submodule update --init --recursive
--recursive 参数很重要。如果你的子模块本身也有子模块（嵌套子模块），必须加上这个参数。
更新 Submodule
更新单个子模块
# 进入子模块目录
cd libs/components
# 拉取最新代码
git pull origin main
# 回到主项目并提交更新
cd ../..
git add libs/components
git commit -m "chore: 更新 shared-components 子模块"
批量更新所有子模块
# 更新所有子模块到最新
git submodule update --remote --merge
# 如果有冲突，强制 rebase
git submodule update --remote --rebase
--remote 会让子模块拉取远程仓库的最新代码，而不是使用主项目锁定的 commit。
一键更新所有子模块
在项目根目录执行：
git submodule foreach 'git pull origin main'
这条命令会对每个子模块执行 git pull。
常见问题与解决方案
问题一：克隆后子模块目录为空
error: pathspec 'libs/components' did not match any file(s) known to git
原因： 没有初始化子模块。
解决：
git submodule init
git submodule update
或者一步到位：
git submodule update --init --recursive
问题二：子模块显示为 modified
Changes not staged for commit:
(use "git add <file>..." updated subrepository)
modified: libs/components (new commits)
原因： 子模块的 commit 和主项目记录的不一致。
解决： 要么更新子模块到主项目锁定的版本：
git submodule update
要么把当前子模块状态提交到主项目：
git add libs/components
git commit -m "update submodule to latest"
问题三：切换分支后子模块出错
git checkout another-branch
# 报错：submodule 'libs/components' not found
原因： 不同分支可能使用了不同的子模块。
解决：
git submodule sync
git submodule update --init
问题四：子模块更新冲突
git submodule update --remote --merge
# Merge conflict in libs/components/src/utils.js
解决： 手动解决冲突后提交：
# 在子模块目录中解决冲突
cd libs/components
# 编辑冲突文件...
git add .
git commit -m "resolve merge conflict"
# 回到主项目
cd ../..
git add libs/components
git commit -m "chore: resolve submodule conflict"
问题五：CI/CD 流水线中子模块失败
很多 CI 工具默认不会处理子模块。需要在流水线配置中添加：
GitHub Actions：
- uses: actions/checkout@v4
with:
submodules: recursive
Jenkins： 安装 Git Submodule Plugin
GitLab CI：
before_script:
- git submodule update --init --recursive
移除 Submodule
移除子模块比添加它麻烦得多。需要清理三个地方：.gitmodules 文件、.git/config 中的配置、以及子模块目录。
# 第一步：卸载子模块
git submodule deinit -f libs/components
# 第二步：从 .gitmodules 中删除
git rm -f libs/components
# 第三步：清理 .git 目录中的残留
rm -rf .git/modules/libs/components
# 第四步：提交更改
git commit -m "chore: remove shared-components submodule"
注意第三步不能省略。很多人删完 .gitmodules 和目录，发现 .git/config 里还有子模块配置残留，后续操作会报错。
替代方案对比
Submodule 不是唯一的选择。以下是几种常见的依赖管理方式：
| 方案 | 优点 | 缺点 |
|---|---|---|
| Submodule | 精确控制版本，独立维护 | 命令复杂，容易出错 |
| Subtree | 不需要特殊命令，普通 Git 操作 | 历史记录不保留，合并冲突多 |
| Monorepo | 一次提交更新所有依赖 | 仓库体积大，CI 慢 |
| 包管理器 | 简单，自动化程度高 | 不适合非标准包格式 |
Subtree 示例：
# 添加 subtree
git subtree add --prefix libs/components https://github.com/example/shared-components.git main --squash
# 更新 subtree
git subtree pull --prefix libs/components https://github.com/example/shared-components.git main --squash
Subtree 的优势是不需要 submodule 系列命令，克隆项目时也不会有额外步骤。代价是失去了子模块的独立性——你无法单独给子模块发 PR。
最佳实践
1. 始终锁定 commit hash
不要依赖分支名。在生产环境中，让上游随意 push 代码是很危险的。
# 查看当前子模块的 commit
git submodule status
# 输出：a1b2c3d libs/components (v2.1.0-10-ga1b2c3d)
# 在提交时记录完整 hash
git add libs/components
git commit -m "deps: update shared-components to a1b2c3d"
2. 编写子模块更新文档
在 README 中明确说明如何初始化子模块：
## 开发环境搭建
1. 克隆项目：
```bash
git clone --recurse-submodules https://github.com/example/my-project.git
- 如果已经克隆，初始化子模块：
git submodule update --init --recursive
### 3. 定期审查子模块更新
设置定时任务或 CI 检查，提醒团队哪些子模块有可用更新：
```bash
# 检查所有子模块是否有新提交
git submodule foreach 'echo "=== $name ===" && git log HEAD..origin/main --oneline'
4. 使用 .gitmodules 的 shallow 选项
对于大型子模块，可以限制克隆深度：
[submodule "libs/components"]
path = libs/components
url = https://github.com/example/shared-components.git
shallow = true
5. 考虑迁移到 Monorepo
如果你的项目超过 5 个子模块，Submodule 的管理成本会很高。这时候 Monorepo（比如 Turborepo、Nx、Bazel）可能是更好的选择。
总结
Submodule 的核心原则就一条：主项目只记录子模块的 commit hash，不管理子模块的代码。
记住几个关键命令：
git submodule add— 添加git submodule update --init --recursive— 初始化git submodule update --remote— 更新git submodule foreach— 批量操作git submodule deinit + git rm— 移除
掌握了这些，Submodule 就不再是噩梦。
你的项目用了多少个子模块？有没有遇到什么奇怪的问题？评论区聊聊。