前言
在 Git 依赖管理中，Submodule 和 Subtree 是两种主流方案，二者虽均能实现 “主仓库集成子仓库” 的需求，但核心机制、操作逻辑和适用场景差异显著。
本文将从核心原理、使用方式、优缺点三个维度深度对比，结合实际开发场景给出选择建议，帮助解决项目依赖管理问题。
1、核心原理对比：“引用跟踪” vs “代码合并”
Submodule 和 Subtree 的本质差异源于对 “子仓库代码” 的管理方式，这直接决定了二者的操作逻辑和适用范围：
| 特性 | Git Submodule | Git Subtree |
|---|
| 核心机制 | 主仓库仅跟踪子仓库的 “引用信息”（URL、当前 commit 哈希），不存储子仓库代码 | 主仓库直接合并子仓库的完整代码，将子仓库作为主仓库的子目录管理 |
| 代码存储 | 子仓库代码独立存储在 .git/modules 目录，主仓库仅记录引用 | 子仓库代码与主仓库代码混合存储在工作区（如 src/external/ui） |
| 配置文件 | 生成 .gitmodules 文件，记录子模块路径、URL、分支等配置 | 无额外配置文件，依赖命令参数（如 --prefix）指定子目录 |
| 提交历史独立性 | 主仓库与子仓库的提交历史完全独立，子仓库的提交不会混入主仓库 | 主仓库可选择保留子仓库独立历史（不使用 --squash）或压缩为单个提交（使用 --squash） |
2、使用方式对比：操作流程与命令差异
2.1 核心操作流程对比
以 “添加子仓库 → 克隆主仓库 → 更新子仓库 → 推送子仓库修改” 为核心流程，对比二者的操作差异：
（1）添加子仓库
| 步骤 | Git Submodule | Git Subtree |
|---|
| 命令 | git submodule add <子仓库URL> <本地路径> | git subtree add --prefix=<本地路径> <子仓库URL> <分支> --squash |
| 关键参数 | 无需额外参数，路径直接指定子模块在主仓库的位置 | --prefix：指定子仓库在主仓库的子目录；--squash：压缩子仓库历史为单个提交（推荐） |
| 操作结果 | 1. 生成 .gitmodules 配置文件2. 子模块目录（如 libs/utils）为空，需后续拉取代码 | 1. 子仓库代码直接合并到指定目录（如 src/ui）2. 主仓库生成 1 个提交（压缩后的子仓库历史） |
| 示例 | git submodule add github.com/x/utils.git libs/utils | git subtree add --prefix=src/ui github.com/x/common-ui… main --squash |
（2）克隆含子仓库的主仓库
Submodule 因 “不存储子仓库代码”，克隆后需额外操作拉取子代码；Subtree 因 “合并子代码”，克隆后可直接使用：
| 操作 | Git Submodule | Git Subtree |
|---|
| 基础克隆命令 | git clone <主仓库URL>（克隆后子模块目录为空） | git clone <主仓库URL>（克隆后子仓库代码已存在） |
| 补充操作 | 需执行 git submodule init && git submodule update（或克隆时加 --recurse-submodules） | 无需额外操作，直接使用子目录代码 |
| 痛点 | 需要执行 init/update 拉取子模块代码 | 无额外操作成本，协作体验更流畅 |
（3）更新子仓库（拉取子仓库最新代码）
| 操作 | Git Submodule | Git Subtree |
|---|
| 命令 | 1. 进入子模块目录 2. 拉取更新：git pull origin main3. 回主仓库提交引用：git commit -am "update utils submodule" | 直接在主仓库根目录执行：git subtree pull --prefix=src/ui github.com/x/common-ui… main --squash |
| 核心逻辑 | 先更新子模块代码，再更新主仓库中子模块的引用（commit 哈希） | 直接将子仓库最新代码合并到主仓库子目录，生成 1 个合并提交 |
| 冲突处理 | 冲突发生在子模块目录，需在子模块内解决后提交 | 冲突发生在主仓库子目录，直接在主仓库内解决并提交 |
（4）推送子仓库修改（主仓库修改子代码后同步到原子仓库）
| 操作 | Git Submodule | Git Subtree |
|---|
| 命令 | 1. 进入子模块目录：cd libs/utils2. 提交修改：git commit -am "fix utils bug" 3. 推送子模块：git push origin main4. 回主仓库提交引用更新 | 1. 主仓库提交修改：git commit -am "fix ui component" 2. 推送子仓库：git subtree push --prefix=src/ui github.com/x/common-ui… main |
| 核心逻辑 | 子模块修改需单独推送（子仓库独立维护），主仓库仅同步引用 | 子仓库修改随主仓库提交后，通过 subtree push 定向推送到原子仓库 |
| 权限依赖 | 需子模块仓库的推送权限（子模块独立管理） | 需子仓库的推送权限（但可仅在主仓库本地修改，不推送） |
（5）删除子仓库
| 操作 | Git Submodule（步骤繁琐） | Git Subtree（步骤简洁） |
|---|
| 命令 | 1. 解除关联：git submodule deinit -f libs/utils2. 删除索引：git rm --cached libs/utils3. 删除文件：rm -rf libs/utils .git/modules/libs/utils4. 提交删除：git commit -am "remove utils submodule" | 1. 删除子目录：rm -rf src/ui2. 提交删除：git commit -am "remove ui subtree" （可选）清理历史：git filter-repo --path src/ui --invert-paths |
| 痛点 | 需清理配置文件、索引、子模块仓库目录，易遗漏 | 仅需删除子目录并提交，操作直观 |
2.2 关键命令速查表
| 操作场景 | Git Submodule 命令 | Git Subtree 命令 |
|---|
| 添加子仓库 | git submodule add <路径> | git subtree add --prefix=<路径> <分支> --squash |
| 克隆主仓库并拉子码 | git clone --recurse-submodules <主仓库URL> | git clone <主仓库URL>（无需额外命令） |
| 更新子仓库 | git submodule update --remote <路径> | git subtree pull --prefix=<路径> <分支> --squash |
| 推送子仓库修改 | 进入子模块目录：git push origin <分支> | git subtree push --prefix=<路径> <分支> |
| 查看子仓库状态 | git submodule status | git subtree status --prefix=<路径> |
3、优缺点对比：适用场景的核心依据
3.1 Git Submodule 优缺点
| 优点 | 缺点 |
|---|
| 1. 版本精确控制：主仓库跟踪子模块的特定 commit，确保所有开发者使用相同子版本，避免兼容性问题2. 子仓库独立维护：子模块的提交历史、分支管理完全独立，适合多人协作维护子仓库3. 主仓库体积小：仅存储子模块引用，不占用主仓库存储空间 | 1. 操作繁琐：需额外执行 init/update 等命令，协作中易因操作遗漏导致代码缺失2. 学习成本高：需理解 “引用跟踪” 机制，新手易混淆主仓库与子模块的版本关系3. 删除复杂：需多步骤清理配置和文件，易残留冗余数据 |
3.2 Git Subtree 优缺点
| 优点 | 缺点 |
|---|
| 1. 操作简洁：无需额外配置文件，核心操作仅需 add/pull/push 三个命令，新手易上手2. 协作友好：克隆主仓库后直接获取子代码，无额外操作成本3. 修改直观：可在主仓库内直接修改子仓库代码，无需切换目录4. 删除简单：仅需删除子目录并提交，无残留文件 | 1. 主仓库体积增大：子仓库代码合并到主仓库，长期使用会导致主仓库体积膨胀2. 版本控制模糊：仅能基于分支同步子仓库，无法精确指定子仓库的某个 commit（需手动记录哈希）3. 历史冗余：若不使用 --squash，子仓库的大量提交会混入主仓库历史，影响可读性 |
3.3 核心差异对比
Git Subtree 与 Git Submodule 的差异：
| 对比维度 | Git Subtree | Git Submodule |
|---|
| 代码存储方式 | 子仓库代码直接作为主仓库的一部分存储 | 主仓库仅存储子仓库的引用（URL、commit 哈希），不存储代码 |
| 配置文件 | 无需额外配置文件，主仓库直接管理子目录代码 | 生成 .gitmodules 配置文件，记录子模块信息 |
| 克隆项目后操作 | 克隆主仓库后直接获取子仓库代码，无需额外步骤 | 需执行 git submodule init/update 拉取子模块代码 |
| 提交历史 | 主仓库可包含子仓库的代码变更历史（可选保留独立历史） | 主仓库与子仓库的提交历史完全独立 |
| 代码修改与推送 | 可在主仓库中直接修改子仓库代码，并推送到原子仓库 | 需进入子模块目录修改代码，再单独推送子仓库 |
| 适用场景 | 追求简洁性、低学习成本，需频繁修改子仓库代码的场景 | 子仓库独立维护、更新频率低，需精确控制版本的场景 |
4、总结
最后总结一下：
- 子仓独立维护、版本需精准、主仓要轻量 → 选 Submodule；
- 子仓需常改、协作人多、新手易上手 → 选 Subtree；
- 特殊场景灵活配，脚本 / 清理来折中。
