子模块目录变空、显示 modified、ci 构建失败，源于主分支记录的子模块 commit id 与当前检出状态不一致；git checkout 或 git switch 需加 --recurse-submodules 参数同步子模块。
切换分支时子模块目录变空、显示 modified、CI 构建失败——这些问题基本都源于主分支记录的子模块 commit ID 与当前检出状态不一致，而 Git 不会自动帮你对齐。
git checkout 或 git switch 时子模块没同步？用 --recurse-submodules
旧版 Git（git status 立刻报 modified。新版 Git（≥2.13）支持 --recurse-submodules 参数，它会在切换分支时自动执行：
- 更新子模块路径下 .git/modules/ 中的引用
- 检出主分支在该分支上记录的 commit ID（不是远程最新）
- 保持子模块工作区与主仓库索引一致
推荐始终使用：
git switch --recurse-submodules feature/login
而不是 git switch feature/login。若已切错，可补救：
git submodule update --init --recursive
为什么 git pull 后子模块还是旧代码？因为默认不拉子模块远程最新
git pull 只更新主仓库，对子模块仅更新其 commit 指针（如果远程分支有新提交并被 push 过），但不会自动 git submodule update --remote。常见误解是“pull 就等于全部最新”，其实不是。
要让子模块也同步到其配置分支（如 .gitmodules 中的 branch = develop）的最新提交，必须显式执行：
git submodule update --remote --rebase
注意：
-
--remote表示从子模块远程仓库拉取指定分支（由.gitmodules的branch字段决定）的最新提交 -
--rebase避免产生无意义合并提交；若需保留历史线性，也可用--merge - 执行后，子模块目录会检出新 commit，但主仓库尚未记录——必须
git add my-submodule并提交，否则下次 clone 仍用旧指针
子模块显示 modified 却没改任何文件？检查 HEAD 是否 detached
进入子模块目录后执行 git status，若看到 HEAD detached at abc123，说明你当前不在任何分支上，只是检出了某个固定 commit。这是子模块的常态，但容易引发误操作。
当你在子模块里做了修改、提交、甚至 push，主仓库并不知道——它只认 commit ID。所以：
- 若想让子模块长期跟踪某分支（如
main），应在子模块内执行git switch main，再git pull - 然后回到主仓库，运行
git add my-submodule提交新指针 - 切忌在 detached HEAD 下直接提交，否则该 commit 很可能丢失（没人引用它）
更稳妥的做法：所有子模块变更都在其 own repo 的分支上开发，通过 PR 合并，再由主项目更新指针。
clone 新项目时子模块为空？初始化和更新必须分两步
git clone 默认不拉取子模块内容，只建好目录结构和 .gitmodules。这是设计使然，不是 bug。
完整流程只有两步，缺一不可：
git clone --recurse-submodules https://github.com/your-org/main-project.git
或（如果已 clone 完）：
git submodule init<br>git submodule update --recursive
注意：
-
--recursive对嵌套子模块必需；若子模块里还有子模块，单用--init不够 - CI 脚本中务必显式加这两步，不能假设
git clone自动搞定 - 某些 CI 环境（如 GitHub Actions）默认禁用递归 clone，需手动开启
子模块的本质是“静态快照”，不是活链接。所有对齐动作都得手动触发，没有后台服务帮你盯着。最容易被忽略的是：每次合入含子模块变更的 PR 前，必须确认 git add 已把新 commit ID 记进主仓库索引——否则别人拉下来，永远卡在旧版本。
