还在手动复制粘贴公共组件到新项目？或者为了同步几个仓库的代码焦头烂额？今天带你彻底搞懂 Git 子模块，学会这招，开发效率直接翻倍。
别再写一堆冗余脚本了，Git 原生支持，谁用谁香！
一、什么是子模块？为什么你需要它？
简单来说，子模块就是一个“套娃”机制。它允许你把一个 Git 仓库作为另一个 Git 仓库的子目录。
1.1 核心应用场景
- 组件库复用：多个项目共用同一个 UI 组件库或工具类库。
- 第三方依赖：不想用 npm 包，想直接引用源码但又想保持独立更新。
- 微服务模块：将配置文件或公共脚本剥离出来，独立维护。
生活化类比：子模块就像你家客厅里的**“独立储物间”**。它属于你房子（主仓库）的一部分，但它有自己独立的门锁（Git 历史），你要进去拿东西（更新代码）得按它自己的规矩来，不能直接在大客厅里乱翻。
二、3 步快速上手：添加子模块
话不多说，直接上代码。
2.1 添加子模块命令
确保你在主仓库根目录下，执行：
# 基本语法
git submodule add <子仓库的URL> <本地路径>
# 实战示例：把 utils 库放到 libs/utils 下
git submodule add https://github.com/example/utils.git libs/utils
2.2 发生了什么？
执行完命令，你会发现：
- 多了个
.gitmodules文件（这是子模块的“身份证”，记录了 URL 和路径）。 libs/utils目录下有了代码，但注意！这个目录处于一个特殊的“分离 HEAD”状态，它仅仅是一个指向特定 commit 的指针。
2.3 提交更改
别忘了把“身份证”和“指针”提交到主仓库：
git add .gitmodules libs/utils
git commit -m "添加 utils 子模块"
git push
三、避坑指南：团队协作如何 Clone？
这是新手最容易踩的坑！
队友 clone 主仓库后，往往发现子模块目录是空的，一脸懵逼 😭。
3.1 正确的克隆姿势
# 方法一：一步到位（推荐）
git clone --recurse-submodules <主仓库URL>
一句话总结：这就好比买房带装修，--recurse-submodules 把家具（子模块代码）一次性给你搬齐了，省得你还得自己跑一趟。
3.2 忘记加参数怎么办？
如果已经 clone 完了，补救措施：
git submodule update --init --recursive
四、进阶实战：强制更新 dev 分支（核心干货 🔥）
很多开发者被这个问题折磨过：你的子仓库在 dev 分支活跃开发，但 git submodule update --remote 默认只会拉取 main（或 master）。
结果就是：明明远程 dev 分支有新代码，你死活更新不下来，以为 Git 坏了。其实是你没用对姿势。
4.1 永久设置跟踪 dev 分支（推荐方案）
我们要给子模块“立个规矩”，告诉它以后跟着 dev 走。
# 配置子模块跟踪 dev 分支
git config -f .gitmodules submodule.libs/utils.branch dev
# 同步配置
git submodule sync --recursive
以后，只需一条命令，就能更新到 dev 的最新代码：
git submodule update --remote --recursive
这波操作绝了，配置一次，终身受用。记得把 .gitmodules 的改动提交并 push，这样队友们也能自动享受到这个配置。
4.2 检查是否配置成功
怎么知道子模块到底听谁的话？
# 查看配置文件
cat .gitmodules
# 查看状态（注意前面的 commit hash 和分支名）
git submodule status
五、常用操作与删除复盘
5.1 更新子模块
平时开发中，子模块更新了，主仓库怎么感知？
# 方式一：拉取远程最新 commit（推荐）
git submodule update --remote
# 方式二：进入子模块目录手动操作
cd libs/utils
git pull origin dev
cd ..
git add libs/utils
git commit -m "更新子模块指针"
5.2 删除子模块（慎用 ⚠️）
Git 目前没有一条命令能完美“一键删除”，需要手动清理残留，确实有点反人类。
# 1. 反初始化子模块
git submodule deinit -f -- libs/utils
# 2. 删除目录
git rm -f libs/utils
# 3. 清理 .git 目录下的缓存（这一步最容易被忘）
rm -rf .git/modules/libs/utils
# 4. 手动检查并删除 .gitmodules 中的相关配置
vim .gitmodules
总结一下：删除子模块就像拆墙，得把墙推倒（目录删掉），还得把建筑图纸（.git 缓存）销毁，否则以后重建容易出问题。
六、总结升华
技术的本质是解决问题。
Git 子模块虽然配置起来稍微有点繁琐，但它完美解决了“代码复用”与“独立维护”的矛盾。如果你还在多个项目里手动复制粘贴公共代码，赶紧停下来试试 Submodule 吧。
核心建议：
- 少量第三方库用 Submodule，太多会很乱。
- 团队统一规范，大家都用
--recurse-submodules克隆。 - 记得配置
.gitmodules跟踪指定分支，避免不必要的踩坑。
我是海潮，专注后端/全栈技术分享，深耕 Git 工程化领域多年，关注我，一起成长、少踩坑 ✨。
