git submodule add 仅注册子模块配置而不拉取代码是设计使然，因它只修改.gitmodules、写入索引和创建元数据；必须执行git submodule update --init才克隆并检出指定commit。
git submodule add 为什么只在父仓库记录路径，不自动拉取代码
执行 git submodule add 后，子模块目录是空的，这是正常行为——Git 只把子模块的 URL 和提交哈希写进 .gitmodules 和父仓库的 index 中，并不立即克隆。很多人误以为“加了就等于有了”，结果后续 git checkout 或 CI 构建时直接报错“目录不存在”或“未初始化”。
正确做法是分三步走：
- 运行
git submodule add（例如git submodule add https://github.com/user/libfoo.git libs/libfoo） - 提交
.gitmodules和新增的子模块索引：git add .gitmodules libs/libfoo && git commit -m "add libfoo as submodule" - 新克隆父仓库的用户必须手动运行：
git submodule init && git submodule update（或一步：git submodule update --init）
子模块更新后，父仓库为什么没自动记录新提交
子模块本质是父仓库中一个“指向特定提交的指针”。你在子模块目录里 git pull origin main 更新了代码，父仓库完全不知道——它仍指向旧的 commit hash。如果不手动提交这个变更，协作时别人检出的还是旧版本，极易引发隐性 bug。
安全更新流程如下：
- 进入子模块目录：
cd libs/libfoo - 拉取最新代码并切换到目标分支/commit：
git pull origin main（或git checkout v2.1.0） - 回到父目录：
cd .. - 查看状态：
git status会显示modified: libs/libfoo (new commits) - 把这个变更提交：
git add libs/libfoo && git commit -m "update libfoo to 6a7b3c1"
git submodule update --recursive 什么时候必须用
当子模块自己也包含子模块（即嵌套 submodule）时，普通 git submodule update 只会拉取一级子模块，内层依然为空。CI 脚本、本地全量构建或跨团队交付前，漏掉 --recursive 就会导致编译失败或运行时 missing dependency。
但要注意副作用：
-
--recursive会递归初始化并更新所有层级，耗时明显增加 - 如果某层子模块的 URL 不可访问（比如私有仓库权限不足），整个命令会中断，且不会回滚已更新的部分
- 推荐在 CI 中显式拆解：
git submodule sync --recursive（同步 URL 变更） +git submodule update --init --recursive（确保全部就位）
如何让 CI 正确检出带 submodule 的项目
GitHub Actions、GitLab CI 默认只做浅克隆（--depth=1），而 submodule 的 commit hash 可能不在父仓库的浅历史里，导致 git submodule update 失败，报错类似 fatal: reference is not a tree: abc123...。
解决方法取决于平台，核心都是绕过浅克隆限制：
- GitHub Actions：在
checkoutstep 加参数fetch-depth: 0，再加submodules: recursive - GitLab CI：设置
GIT_DEPTH: 0（或直接删掉variables: { GIT_DEPTH: 1 }） - 自建 Jenkins/Git：改用完整克隆命令：
git clone --recurse-submodules --shallow-submodules（注意--shallow-submodules是可选优化，非必需）
别依赖“父仓库 commit 页面点开子模块链接就能看到最新代码”——那只是 GitHub 渲染的跳转，实际检出仍以父仓库记录的 commit hash 为准。只要没提交那个 hash 变更，别人就看不到你本地的更新。
