Git Submodule 基础使用指南：管理项目依赖的高效方案

概述

做多人协作或者稍复杂的项目时，经常要把别的独立 Git 仓库（比如公共组件库、工具模块）当依赖引用进来。Git Submodule（子模块）就是为这个场景准备的 —— 它能把一个 Git 仓库塞进另一个 Git 仓库当“子目录”，但两边各自的版本控制还是独立的：主项目只记一下子模块的“引用信息”（仓库地址、当前版本这些），子模块自己该有的完整 Git 历史和提交记录都还在。

比起直接把依赖代码复制进来（版本容易乱）、或者用包管理工具（npm、pip 这种，还得额外维护一个包仓库），Git Submodule 的好处是：

1. 版本卡得准：主项目能指定子模块用哪个具体提交，不会被依赖自动升级带出兼容性问题；
2. 两边各管各的：子模块可以独立更新，主项目按需同步，互不耽误；
3. 集成轻：不用额外装工具，Git 自带命令就能管，学习成本不高。

这篇文章从“添加子模块”“更新子模块”“删除子模块”这几个核心场景入手，把 Git Submodule 的完整用法捋一遍，帮你快速上手依赖管理。

一、核心操作：从添加到删除的全流程

Git Submodule 的操作其实就是围着子模块的“生命周期”转，下面按每个阶段把命令和注意点讲清楚。

1. 初始化子模块（首次使用）

如果你克隆的主项目里已经配好了子模块（仓库里有 .gitmodules 文件），得先初始化子模块、把依赖代码拉下来，不然子模块那个目录是空的：

# 1. 初始化子模块（读取 .gitmodules 配置，注册子模块信息到主项目的 .git 目录）
git submodule init

# 2. 拉取子模块的具体代码（根据初始化的配置，克隆子模块仓库到指定目录）
# （推荐合并命令：init + update 一步完成，避免遗漏）
git submodule update --init --recursive
# --init：执行 init 操作（若未初始化）
# --recursive：若子模块内部还包含子模块（嵌套子模块），会一并拉取（避免嵌套依赖缺失）

场景示例：克隆了带子模块的项目后，直接跑 git submodule update —init —recursive，就能一次性把子模块初始化好并把代码拉下来。

2. 给主项目添加新的子模块

要是想在自己主项目里引入一个新的子模块（比如引用公共组件库），用 git submodule add 命令，把子模块的仓库地址和本地存放目录给定好：

# 基本语法：git submodule add <子模块仓库地址> [本地存放目录]
git submodule add https://github.com/example/common-ui.git src/common-ui

命令说明：

• <子模块仓库地址>：子模块的 Git 仓库 URL（支持 HTTPS、SSH 格式，如 git@github.com:example/common-ui.git）；
• [本地存放目录]：可选参数，指定子模块在主项目中的存放路径（如 src/common-ui）；若不指定，默认以子模块仓库名作为目录名（如 common-ui）。

执行后发生的变化：

• 主项目里会多出来一个子模块目录（比如 src/common-ui），里面是子模块的代码；
• 主项目根目录会生成一个 .gitmodules 文件（核心配置，记着“仓库地址 - 本地目录”的对应关系，得提交到主项目仓库，别人才同步得了）；
• 主项目的 Git 暂存区会多出两条记录：.gitmodules 文件和子模块目录（要执行 git commit 提交，不然子模块配置不会保存）。

提交配置：加完子模块后，必须把配置提交到主项目仓库，不然别人克隆项目时拿不到子模块的信息：

git add .gitmodules src/common-ui  # 将配置文件和子模块目录加入暂存区
git commit -m "feat: 添加公共组件库子模块 common-ui"  # 提交到主项目
git push  # 推送到远程仓库

3. 更新子模块（同步依赖变更）

子模块更新分两种情况：一种是主项目去同步子模块的最新版本，另一种是子模块自己改了代码要提交，这两种得分开处理。

场景 1：主项目拉取子模块的最新代码

要是子模块的远程仓库更新了（比如组件库发了新功能），主项目这边得手动去同步这些变更：

# 方式 1：进入子模块目录，执行 git pull（适合单个子模块更新）
cd src/common-ui  # 进入子模块目录
git checkout main  # 切换到子模块的目标分支（如 main、develop）
git pull  # 拉取该分支的最新代码
cd ../..  # 回到主项目根目录

# 方式 2：在主项目根目录执行，批量更新所有子模块（推荐，效率更高）
git submodule update --remote --merge
# --remote：表示从子模块的远程仓库拉取最新代码（而非按主项目记录的版本）
# --merge：若主项目对其子模块有本地修改（不推荐），会尝试合并远程更新（避免直接覆盖）

场景 2：子模块本地修改后提交到远程

如果你在主项目里改了子模块的代码（比如修了组件库的一个 bug），得先在子模块目录里把改动提交，再回到主项目同步子模块的版本引用：

# 1. 进入子模块目录，提交修改到子模块的远程仓库
cd src/common-ui
git add .  # 将子模块的修改加入暂存区
git commit -m "fix: 修复按钮点击事件bug"  # 提交到子模块的本地仓库
git push  # 推送到子模块的远程仓库（需子模块仓库的权限）
cd ../..  # 回到主项目根目录

# 2. 主项目同步子模块的版本引用（关键步骤！否则主项目仍记录旧版本）
# 此时主项目会检测到子模块的版本已变更，执行 git status 会看到子模块目录处于 "modified" 状态
git add src/common-ui  # 将子模块的新版本引用加入暂存区
git commit -m "refactor: 同步 common-ui 子模块到最新版本"  # 提交到主项目
git push  # 推送到主项目的远程仓库

注意：子模块的改动必须先提交到子模块自己的远程仓库，再去更新主项目的版本引用 —— 要是跳了第一步直接提主项目，别人拉下来后找不到子模块对应的版本，就会报错。

4. 克隆含子模块的项目（新手必看）

克隆一个带子模块的主项目时，默认只会把主项目代码拉下来，子模块目录是空的（只留个目录壳子），得额外跑命令把子模块代码拉下来：

# 1. 先克隆主项目（常规操作）
git clone https://github.com/example/my-project.git
cd my-project  # 进入主项目目录

# 2. 拉取所有子模块的代码（初始化 + 更新一步完成）
git submodule update --init --recursive
# 执行后，子模块目录会被填充具体代码，可正常使用

简化命令：Git 1.9 及以上版本支持克隆时顺手把子模块一起拉了，不用再额外操作：

git clone --recursive https://github.com/example/my-project.git
# --recursive：克隆主项目的同时，自动初始化并拉取所有子模块（推荐）

5. 删除子模块（移除依赖）

要是主项目不想再要某个子模块了，得把它的“代码、配置、Git 记录”彻底删干净，免得残留文件影响后面操作（直接删子模块目录会让 Git 报错）：

# 步骤 1：解除子模块与主项目的关联（删除主项目 .git 目录中对子模块的记录）
git submodule deinit src/common-ui
# src/common-ui：子模块在主项目中的本地目录（需与添加时的路径一致）

# 步骤 2：从主项目的 Git 暂存区中移除子模块目录（不删除本地文件，仅删除 Git 跟踪）
git rm --cached src/common-ui
# 执行后，主项目的 .gitmodules 文件中对应子模块的配置会被删除

# 步骤 3：（可选）手动删除子模块的本地代码目录和残留的 Git 信息（彻底清理）
rm -rf src/common-ui  # 删除子模块的本地代码
rm -rf .git/modules/src/common-ui  # 删除主项目 .git 目录中残留的子模块 Git 仓库信息

# 步骤 4：提交删除操作到主项目仓库
git add .gitmodules  # 提交 .gitmodules 文件的变更（删除了子模块配置）
git commit -m "feat: 移除 common-ui 子模块"
git push

注意：git submodule deinit 和 git rm —cached 是核心两步，缺一个都不行 —— 前者解除关联，后者移除跟踪；要是跳过 deinit 直接 git rm，主项目 Git 配置会残留，以后再添加同名子模块可能报错。

二、常用辅助命令与注意事项

1. 查看当前子模块状态

想看主项目里所有子模块现在用的什么版本、有没有没同步的改动，用这个：

git submodule status
# 输出示例：
#  a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0 src/common-ui (v1.2.0-1-g1234567)
#  说明：a1b2c... 是子模块当前的提交哈希，src/common-ui 是子模块目录，(v1.2.0...) 是子模块的版本标签

2. 批量拉取主项目与子模块的更新

若主项目和子模块均有远程更新，可一次性拉取所有变更：

# 方式 1：先拉取主项目更新，再更新子模块
git pull  # 拉取主项目的最新代码
git submodule update --remote --recursive  # 拉取所有子模块的最新代码

# 方式 2：一步拉取主项目和子模块（Git 2.13+ 支持）
git pull --recurse-submodules
# --recurse-submodules：拉取主项目后，自动更新所有子模块到最新版本

3. 注意事项（避坑指南）

• 版本是被锁死的：主项目记的是子模块的“特定提交哈希”，不是分支 —— 就算子模块远程分支（比如 main）更新了，主项目默认还是用旧版本，得手动跑 git submodule update —remote 去同步，免得“依赖自动升级带出兼容问题”；
• 嵌套子模块：如果子模块里面还套着子模块（比如组件库又依赖工具库），操作时记得加 —recursive（如 git submodule update —init —recursive），不然里层的子模块会缺；
• 多人协作要提交：添加 / 删除子模块之后，必须把 .gitmodules 文件和子模块目录的改动提交到主项目远程仓库，不然别人同步不了这些配置；
• 别在主项目里直接改子模块：除非你就是子模块的维护者，否则不建议在主项目里改子模块代码 —— 要定制的话，先 fork 子模块仓库，再在主项目里引用你自己的 fork 版本，免得跟子模块官方更新打架。

总结

Git Submodule 是 Git 自带的轻量依赖管理方案，最大的好处就是“版本卡得准”和“仓库各管各的”，适合管项目里那种独立的模块（公共组件库、工具函数库之类的）。要把它用明白，关键就三点：

1. 加了子模块之后，记得把 .gitmodules 配置提交了；
2. 克隆带子模块的项目时，记得加 —recursive，或者跑 git submodule update —init —recursive；
3. 删子模块要清干净配置和残留文件，别让 Git 报错。

要是你项目依赖多、还得频繁更新，也可以看看 Git Subtree（另一款 Git 依赖管理工具，把子模块代码直接合进主项目仓库）。不过大多数场景下 Git Submodule 就够用了，而且学起来更轻松。