git submodule 实战与替代方案：嵌套仓库痛点与 monorepo 迁移指南

一、submodule 的设计

父仓库保存两个信息：.gitmodules 中的地址，以及子目录对应的 commit 指针。父仓库并不保存子模块当前分支的最新状态，因此更新子模块后，还必须在父仓库提交新的指针。

这带来明确的版本绑定能力：主项目可以固定依赖某个精确 commit。但它也违反了很多人的直觉：普通 git clone 后子目录可能是空的，修改子模块代码不会自动出现在父仓库 diff 中。

二、添加与克隆

git submodule add https://github.com/example/shared-lib.git vendor/shared-lib
git add .gitmodules vendor/shared-lib
git commit -m "chore: add shared-lib submodule"

递归克隆：

git clone --recurse-submodules https://github.com/example/app.git

已克隆项目初始化：

git submodule update --init --recursive

检查状态：

git submodule status
git -C vendor/shared-lib status

三、更新和开发

更新到远程跟踪分支：

git -C vendor/shared-lib fetch origin
git -C vendor/shared-lib checkout main
git -C vendor/shared-lib pull --ff-only
git add vendor/shared-lib
git commit -m "chore: update shared-lib"

开发流程是先进入子模块提交并推送：

cd vendor/shared-lib
git switch -c fix/timeout
git add .
git commit -m "fix: handle timeout"
git push -u origin fix/timeout
cd ../..
git add vendor/shared-lib
git commit -m "chore: point shared-lib to timeout fix"

如果只提交父仓库指针而没有推送子模块 commit，其他人和 CI 将无法检出对应对象。

四、CI 配置

GitHub Actions：

name: test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pytest

GitLab CI：

test:
  image: python:3.12
  variables:
    GIT_SUBMODULE_STRATEGY: recursive
  script:
    - pip install -r requirements.txt
    - pytest

私有子模块需要 CI Token 或 SSH Deploy Key。密钥必须通过 CI Secret 注入，不能写入 .gitmodules URL 或脚本。

五、常见八个坑

1. 克隆后空目录：没有使用 --recurse-submodules。
2. 子模块 URL 改了：需要修改 .gitmodules 后执行 git submodule sync --recursive。
3. 忘记提交指针：父仓库仍指向旧 commit。
4. 子模块处于 detached HEAD：这是正常状态，但开发前应切换分支。
5. 嵌套 submodule 未初始化：使用 --recursive。
6. 子模块有本地修改：更新前先提交、暂存或清理。
7. CI 权限不足：检查 Token、SSH 和子仓库可见性。
8. 分支删除后指针不可达：父仓库引用的 commit 必须长期可获取。

修改 URL：

git config -f .gitmodules submodule.vendor/shared-lib.url https://git.example.com/shared-lib.git
git submodule sync --recursive
git submodule update --init --recursive

六、替代方案

git subtree

subtree 把外部仓库内容合并进当前仓库，使用体验接近普通目录：

git subtree add --prefix=vendor/shared-lib \
  https://github.com/example/shared-lib.git main --squash
git subtree pull --prefix=vendor/shared-lib \
  https://github.com/example/shared-lib.git main --squash

优点是克隆一次即可获得完整代码；缺点是历史和同步策略更复杂。

monorepo

monorepo 将多个项目放在一个仓库，通过 pnpm workspace、Nx、Bazel 或 Pants 管理构建和依赖。适合需要原子提交、统一工具链和跨项目重构的团队，但仓库权限、CI 增量构建和代码所有权需要额外设计。

包管理器

如果依赖是稳定库，优先发布 npm、PyPI 或 Go module，通过制品库进行版本管理。这样应用仓库只保存版本号，不承担源码嵌套和同步责任。

七、选型决策

需求	推荐
固定外部仓库 commit	submodule
希望单仓库体验但保留同步	subtree
多项目强耦合、需原子修改	monorepo
独立发布、稳定版本	包管理器

submodule 并不是错误设计，它适合“独立仓库、精确锁定、低频同步”的依赖。若团队每天都要进入子模块开发、同步和发布，通常应认真评估 subtree、monorepo 或制品包。