Git Submodule实战指南：解决多仓库协作的常见痛点

先看效果，再看代码

上周我接手一个老项目，里面有个 UI 组件库被拆成独立仓库了。项目经理说：“用 submodule 引进来就行。” 我心里一咯噔——又得和 Git Submodule 打交道了。这玩意儿说简单也简单，说坑人也真坑人。折腾了两天，总算理顺了。今天就把我踩过的坑和亲测有效的用法写下来，省得你再走弯路。

先上最常用的命令：把一个子模块加进主项目

git submodule add https://github.com/your-org/ui-components.git src/components/ui

执行完后，Git 会在你的项目根目录生成一个 .gitmodules 文件，内容类似这样：

[submodule "src/components/ui"]
	path = src/components/ui
	url = https://github.com/your-org/ui-components.git

同时，src/components/ui 目录会被创建，并且指向子模块的某个 commit（不是分支！）。这时候你跑 git status，会看到两个改动：一个是 .gitmodules，另一个是 src/components/ui 这个“特殊文件”（其实是 Git 记录的指针）。

这个场景最好用

Submodule 最适合什么情况？我觉得是：你有一个稳定、独立、版本清晰的公共库，需要在多个项目中引用，但又不想打包成 npm 包（比如因为构建流程复杂、或涉及私有逻辑）。

举个例子：我们团队有个内部工具库，包含一些通用的表单验证、日期处理函数，它有自己的测试和 CI 流程。每个前端项目都通过 submodule 引入，而不是发到私有 npm。好处是：更新时只需在主项目里切换子模块的 commit，不用处理包发布、缓存、lock 文件等问题。

拉取带 submodule 的项目时，很多人第一次会懵——为什么 src/components/ui 是空的？别急，要两步：

git clone https://github.com/your-org/main-project.git
cd main-project
git submodule init
git submodule update

或者更懒一点，clone 时直接递归拉取：

git clone --recurse-submodules https://github.com/your-org/main-project.git

亲测有效，建议直接用这种方式。不然新人第一次拉代码，看着空目录以为坏了，其实只是没初始化 submodule。

踩坑提醒：这三点一定注意

我在这上面栽过不止一次，血泪教训：

• 子模块默认处于“分离头指针”状态。你进到 src/components/ui 目录里，执行 git status，会看到 “HEAD detached at xxx”。这时候如果你直接改代码并提交，虽然能 push，但主项目并不会自动更新指向。必须回到主项目，手动 git add src/components/ui 并提交，才能把新 commit 关联进去。否则别人拉代码还是旧版本。
• 不要在子模块里切分支然后提交。正确的做法是：在子模块仓库里新建分支、开发、合并到 main，然后在主项目里更新子模块到最新 commit。如果你在主项目的子模块目录里直接 git checkout -b feature，虽然能改，但后续同步极其混乱，容易搞丢提交。
• CI/CD 环境需要额外权限。如果你的 submodule 是私有仓库，CI 脚本里光有主项目的 token 不够，还得配置能访问子模块的凭据。GitHub Actions 里可以用 actions/checkout 的 submodules: true 配合 token 参数，但 GitLab CI 就得自己写 before_script 去配置 SSH 或 token。我之前 CI 一直失败，查了半天才发现是 submodule 拉不下来。

高级技巧：批量更新 & 自动化

当项目里有多个 submodule 时，手动 cd 进去更新太麻烦。Git 提供了批量操作命令：

# 更新所有 submodule 到最新 commit（基于 .gitmodules 里记录的 remote）
git submodule update --remote --merge

# 或者用 --rebase
git submodule update --remote --rebase

不过要注意：--remote 默认会拉取 submodule 的 default branch（通常是 main 或 master），而不是你上次锁定的 commit。所以这招适合“总是想用最新版”的场景。如果要严格控制版本，建议手动在子模块里 git pull，然后回主项目 git add 提交指针变更。

我还写了个小脚本，放在项目根目录，方便团队统一操作：

#!/bin/bash
# update-submodules.sh
echo "Updating submodules..."
git submodule foreach 'git checkout main && git pull origin main'
git add .
git commit -m "chore: update submodules to latest"

虽然粗暴，但对内部项目够用了。记得提醒队友：更新 submodule 后要测试，别盲目 merge。

替代方案？其实也有

有人会问：为啥不用 npm link、yarn workspace、或者直接 copy 代码？我的看法是：

• npm link 适合本地开发调试，但不适合多人协作的生产环境（路径依赖太强）
• yarn workspace 要求所有代码在一个 monorepo 里，如果你的组件库是跨团队、跨项目的，就不合适
• 直接 copy 代码？那更新怎么同步？改十个项目累死你

所以，当你需要“外部引用 + 精确版本控制 + 无需构建依赖”的时候，submodule 依然是最务实的选择。虽然它命令有点反人类，但胜在透明、可控。

结尾碎碎念

Submodule 不是银弹，但它解决了一类非常具体的问题。我现在的项目里，它稳定跑了快一年，只要团队约定好操作规范（比如“禁止在子模块目录直接提交”），基本不会出事。

以上是我踩坑后的总结，希望对你有帮助。这个技巧的拓展用法还有很多（比如结合 sparse-checkout 只拉部分目录），后续会继续分享这类博客。有更优的实现方式欢迎评论区交流——尤其是 CI 那块，如果你有更好的自动化方案，求分享！