Git Submodule vs Subtree：多仓库协作选型与实操指南

1. 多仓库协作的痛点与两套方案的由来

但凡参与过稍微上点规模的项目，迟早会撞上同一个问题：主工程里有一部分代码，你希望它既能独立演进，又能被主工程稳定引用。典型场景包括公共组件库、协议定义文件、设计资源、第三方 SDK 源码、跨团队共享的配置模板等等。最原始的做法是复制粘贴，改一处同步三处，时间一长必然出现版本漂移；稍微讲究一点的做法是各自建仓库，然后在主工程里手动拉取、手动合并，这又退回到人肉运维的老路。

Git 给出的官方答案有两个：Git Submodule 和 Git Subtree。它们解决的是同一类问题——把外部仓库的内容嵌入到当前仓库中，同时保留一定的独立性和版本可控性——但底层机制、操作手感、协作成本完全不同。选错了，团队里会长期弥漫一种“每次更新都要祈祷”的氛围；选对了，多仓库协作可以做到几乎无感。

这篇内容我会把两者的原理拆到能自己画图的程度，把区别列成能直接对照的表格，再把使用场景落到具体项目形态上。适合正在做架构拆分、组件库治理、或者单纯被 submodule 折磨过的开发者。读完你应该能明确回答一个问题：我这个项目，到底该用哪个。

2. Git Submodule 原理拆解：一个指针，两个仓库

2.1 Submodule 到底存了什么

很多人第一次接触 submodule 会误以为主仓库“包含”了子仓库的代码。事实并非如此。Submodule 在主仓库里只存了三样东西：

• 一条 gitlink 记录，也就是一个特殊的树对象条目，指向子仓库的某个具体 commit（注意是 commit，不是分支）；
• 一个 .gitmodules 文件，记录子仓库的路径和 URL；
• 子仓库自己的 .git 目录，通常以文件形式存在，指向主仓库 .git/modules/ 下的真实 git 目录。

用一句话概括：主仓库记住的是“子仓库在某个时刻的某个 commit”，而不是子仓库的内容本身。这就像你在书架上放了一张便签，写着“第三排那本书的第 42 页”，而不是把那页复印下来贴上去。便签很轻，但书一旦被挪走或改版，便签就可能失效。

这个设计带来一个直接后果：克隆主仓库时，默认不会拉取子仓库的内容。你看到的只是一个空目录。必须显式执行 git submodule update --init --recursive 才能把内容填进去。这是新手最容易踩的第一个坑。

2.2 为什么用 commit 而不是分支

这是 submodule 设计里最关键的一个决策，也是最容易被误解的地方。主仓库记录的是 commit hash，不是分支名。原因很直接：可复现性。

如果主仓库记录的是“子仓库的 main 分支”，那么今天克隆和明天克隆拿到的内容可能完全不同，构建结果无法保证一致。记录 commit 则意味着，只要主仓库的这个 commit 不变，子仓库的内容就永远锁定在那一刻。这对需要长期维护、需要精确回溯的项目来说是刚需。

代价也很明显：子仓库更新后，主仓库不会自动跟进。你必须进入子仓库拉取、切到目标 commit，再回到主仓库 git add 那个目录，提交一次“指针更新”。这个动作在团队协作中经常被遗忘，导致主仓库指向一个过时的 commit，而开发者以为已经更新了。

2.3 常用命令与它们背后的动作

理解命令背后的动作，比死记命令重要得多。下面这张表把常用操作和它实际改了什么对应起来：

命令	实际动作	容易误解的点
git submodule add <url> <path>	克隆子仓库到 path，写入 .gitmodules，暂存 gitlink	会立即克隆，不是只登记
git submodule update --init	按主仓库记录的 commit 检出子仓库	不会拉取最新，只对齐记录
git submodule update --remote	拉取子仓库远程分支最新并检出	会改变工作区，需再提交主仓库
git clone --recurse-submodules	克隆主仓库并递归初始化所有子模块	老版本 git 不支持，需分步执行
git submodule foreach <cmd>	对每个子模块执行命令	顺序按 .gitmodules 排列

注意：git submodule update 默认是“对齐主仓库记录的 commit”，不是“更新到最新”。很多人以为它在更新，其实它只是在还原。真正想拉最新要用 --remote，而且拉完还要回主仓库提交指针。

2.4 Submodule 的协作陷阱

Submodule 最让人头疼的不是命令多，而是状态容易分裂。子仓库处于 detached HEAD 状态是常态，因为它是按 commit 检出的。开发者如果在子仓库里直接改代码并提交，很容易提交到一个游离的 HEAD 上，推不上去，或者推上去了但主仓库没记录，别人拉不到。

另一个高频问题是权限。子仓库往往是独立仓库，有自己的访问控制。主仓库能克隆不代表子仓库能克隆，CI 环境里经常出现主仓库拉下来了、子模块初始化失败的情况。这要求 CI 配置里显式处理子模块的凭证，不能想当然。

3. Git Subtree 原理拆解：把内容真正搬进来

3.1 Subtree 的本质是合并

Subtree 的思路和 submodule 完全相反：它不存指针，而是把子仓库的内容真正合并进主仓库的某个子目录。主仓库里就是实实在在的文件，克隆主仓库就能拿到全部内容，不需要额外初始化。

它的核心机制是 git subtree 命令（注意这是 git 自带的 contrib 脚本，不是核心命令，部分环境需要单独安装）。添加一个 subtree 时，git 会把子仓库的历史合并进来，并记录一个“前缀映射”，告诉 git 这个子目录对应哪个外部仓库。之后主仓库的提交历史里就包含了子仓库的历史，只是被压缩或重写到了子目录下。

3.2 为什么它不需要额外初始化

因为内容已经在主仓库的对象库里了。你 git clone 主仓库，子目录的文件就在那里，历史也在那里。这对 CI、对新加入的同事、对任何只想“拉下来就能跑”的场景都极其友好。没有 .gitmodules，没有初始化步骤，没有 detached HEAD。

代价是主仓库体积会变大，因为子仓库的历史被并进来了。如果子仓库历史很长、文件很大，主仓库的克隆时间会明显增加。这是 subtree 最主要的成本。

3.3 常用命令与动作对应

命令	实际动作	关键点
git subtree add --prefix=<dir> <repo> <branch>	合并子仓库历史到 dir	会产生一个合并提交
git subtree pull --prefix=<dir> <repo> <branch>	拉取子仓库更新并合并	可能产生冲突，需手动解决
git subtree push --prefix=<dir> <repo> <branch>	把 dir 的改动推回子仓库	会重写历史，大仓库较慢
git subtree split --prefix=<dir>	把 dir 的历史拆成独立分支	常用于推回前的准备

提示：git subtree push 在历史很长时会非常慢，因为它要重新计算整个子目录的历史。实践中如果推送频繁，建议配合 split 缓存结果，或者干脆改用 submodule 做双向同步。

3.4 Subtree 的隐性成本

Subtree 看起来“简单”，但它的简单是有代价的。第一，合并冲突会比 submodule 更复杂，因为冲突发生在真实文件层面，而不是指针层面。第二，推回子仓库时历史会被重写，如果多人同时操作，容易出现重复提交或历史分叉。第三，主仓库的 git log 会混入子仓库的提交，排查问题时需要额外过滤。

所以 subtree 并不是“无脑更优”，它只是把复杂度从“协作流程”转移到了“仓库体积和历史管理”上。

4. 两者核心区别对照：一张表看清选型依据

4.1 机制层面的根本差异

维度	Git Submodule	Git Subtree
存储内容	指针（commit hash）	真实文件与历史
克隆后是否可用	需额外 init	直接可用
主仓库体积	小	大
子仓库独立性	强，完全独立	弱，历史被并入
更新方式	手动对齐 commit	pull 合并
双向同步	需进子仓库操作	push 回子仓库
冲突处理	指针层面，较简单	文件层面，较复杂
CI 友好度	需额外配置	开箱即用
学习成本	高	中

4.2 协作层面的差异

Submodule 的协作是“分布式”的：每个仓库有自己的权限、自己的 CI、自己的发布节奏。主仓库只是一个引用者。这适合子仓库由独立团队维护、有独立发布周期的场景。

Subtree 的协作是“集中式”的：主仓库包含了全部内容，子仓库更像是一个同步目标。这适合子仓库和主仓库由同一批人维护、更新频率不高的场景。

4.3 选型决策树

如果你还在纠结，可以按下面这个顺序问自己：

1. 子仓库是否由独立团队维护、有独立权限控制？是 → 倾向 submodule。
2. 是否要求克隆后零配置即可构建？是 → 倾向 subtree。
3. 子仓库更新是否频繁、是否需要频繁双向同步？频繁 → submodule 更稳。
4. 主仓库体积是否敏感？敏感 → submodule。
5. 团队是否熟悉 git 高级操作？不熟 → subtree 上手更快。

5. 使用场景落地：不同项目形态怎么选

5.1 公共组件库场景

公司内部有一套 UI 组件库，被十几个业务项目引用。组件库由基础架构组维护，有独立的版本号和发布流程。这种场景优先 submodule。原因是组件库需要独立演进、独立发版，业务项目锁定某个稳定 commit 即可。用 subtree 的话，每次组件库更新都要合并进每个业务项目，历史会迅速膨胀，而且业务项目之间无法共享同一份组件历史。

5.2 协议与配置文件场景

前后端共享一套 protobuf 定义或 API schema，更新频率不高，且要求所有项目拿到的定义完全一致。这种场景subtree 更合适。因为文件量小、更新少，合并成本低，而且“克隆即可用”对前端同学特别友好，不需要每个人都去学 submodule 初始化。

5.3 第三方 SDK 源码场景

有些项目需要把第三方 SDK 源码嵌进来做定制修改。这种场景要看是否需要回推。如果只是单向引入、本地改，subtree 更简单；如果需要定期同步上游更新并回推自己的修改，submodule 的独立性更有优势。

5.4 文档与设计资源场景

设计稿、图标、文档这类资源，更新频率低、体积可能较大、不需要复杂历史。subtree 的“拉下来就有”特性很契合，但如果体积很大，要考虑主仓库膨胀问题，必要时用 submodule 或干脆用包管理工具。

6. 实操过程：从零搭建两套方案

6.1 Submodule 完整实操

假设主仓库叫 main-app，子仓库叫 shared-lib。

关键点在于最后那三步：进子仓库拉取、回主仓库提交指针。少一步，别人就拉不到你的更新。

6.2 Subtree 完整实操

--squash 的作用是把子仓库的历史压缩成一个提交，避免主仓库历史被大量子仓库提交淹没。代价是丢失了子仓库的细粒度历史。如果不加 --squash，历史完整但主仓库会变重。这是一个需要权衡的参数。

6.3 参数选择背后的计算

以 --squash 为例。假设子仓库有 5000 个提交，每个提交平均影响 3 个文件。不加 squash，主仓库会多出 5000 个提交对象和约 15000 个树对象变更。加 squash，只多出 1 个提交。对于主仓库历史清洁度来说，squash 优势明显。但如果需要追溯子仓库的某次具体修改，squash 后就查不到了。所以选择取决于：你更看重历史清洁，还是更看重可追溯性。

7. 常见问题与排查技巧实录

7.1 Submodule 常见问题速查

问题现象	原因	解决
克隆后子目录为空	未初始化	git submodule update --init --recursive
子模块处于 detached HEAD	按 commit 检出	正常现象，改动前先切分支
推送子模块改动失败	游离 HEAD	切到分支再提交推送
CI 拉取子模块失败	权限或凭证缺失	配置 CI 的子模块访问凭证
主仓库指针不更新	忘记提交 gitlink	回主仓库 git add 后提交

7.2 Subtree 常见问题速查

问题现象	原因	解决
pull 时冲突多	文件层面合并	手动解决后提交
push 极慢	历史重算	用 split 缓存或改 submodule
主仓库体积暴涨	历史被并入	加 --squash 或改 submodule
推回后历史分叉	多人同时 push	约定单人负责推送

7.3 独家避坑经验

第一条经验：submodule 的 URL 尽量用相对路径或统一域名。如果 .gitmodules 里写的是开发者本地能访问但 CI 访问不了的地址，CI 必然失败。统一用公司内部 git 服务的标准地址，减少环境差异。

第二条经验：subtree 的 push 操作要指定专人。因为 push 会重写历史，多人同时操作极易产生重复提交。实践中可以约定只有一个人负责回推，其他人只 pull。

第三条经验：不要在主仓库和子仓库同时改同一批文件。无论 submodule 还是 subtree，这都会导致同步时的冲突。职责边界要清晰：要么子仓库是唯一修改入口，要么主仓库是唯一修改入口。

第四条经验：定期检查 .gitmodules 和实际路径是否一致。submodule 路径改过之后，.gitmodules 可能没同步更新，导致新克隆的人初始化到错误位置。

8. 我个人在实际操作中的体会

用了几年下来，我的判断标准其实很简单：看子仓库是不是“另一个团队的产品”。如果是，用 submodule，把边界划清楚，各自负责各自的发布；如果只是“同一批人维护的共享文件”，用 subtree，别给自己找初始化麻烦。

还有一个很现实的点：团队里总有人不熟悉 git 高级操作。submodule 的初始化步骤对这些人来说是持续的成本，每次新环境搭建都可能卡住。subtree 在这方面的体验优势是实打实的。所以如果团队 git 水平参差，subtree 往往是更稳妥的选择，哪怕它在体积和历史管理上有点代价。

最后分享一个小技巧：如果项目同时有多个子仓库，可以写一个 Makefile 或脚本统一处理初始化和更新，把 git submodule update --init --recursive 和 git subtree pull 都封装进去。这样无论用哪种方案，新人都只需要跑一条命令，把学习成本降到最低。这个脚本本身也值得提交到主仓库，作为项目基础设施的一部分。