CI 中拉取子模块是什么
流水线里的默认克隆往往不含子模块、且只有浅历史：要用 --recurse-submodules 让克隆带上子模块、--shallow-submodules 控制每层深度；私有子模块必须与父仓库在同一套只读凭据下可见，否则构建会卡在拉取子模块这一步，报错信息还常常指向缺文件而不是权限。
基本信息
| 一步克隆 | git clone --recurse-submodules --shallow-submodules --depth 1 <url> |
|---|---|
| 已克隆补齐 | git submodule update --init --recursive --depth 1 |
| 权限 | 子模块与父仓库需同一套只读凭据（部署密钥/令牌） |
| 校验 | git -C app submodule status --recursive，行首全为空格即拉齐 |
| 连通性 | SSH 地址先 ssh -T 验证密钥；HTTPS 用令牌并确认无交互提示 |
典型使用场景
- 全新流水线检出：一条命令带齐所有子模块，不用在构建脚本里补拉。
- 已有工作区补拉：父仓库已克隆后用 update --init --recursive 把子模块补上。
- 控制耗时：子模块只需当前提交时加 --depth 1 与 --shallow-submodules。
- 私有子模块：逐个核对部署密钥对每个子模块仓库都有读权限，缺一不可。
- 历史版本构建：构建旧 tag 时确认子模块对应提交在上游仍可获取。
- 缓存场景：缓存键若只覆盖父仓库内容，恢复后子模块可能是旧指针，纳入校验再决定是否复用缓存。
CI 常用写法
CI 常用写法
git clone --recurse-submodules --shallow-submodules --depth 1 https://example.com/app.git
# 一步带齐子模块，每层只取最新提交，节省流水线时间
git -C app submodule status --recursive # 校验：所有行首都应是空格
git -C app submodule update --init --recursive --depth 1 # 已克隆仓库补拉
ssh -T git@example.com # 子模块走 SSH 时先验证密钥连通性私有子模块漏授权是最常见的失败：先手工单独克隆一次子模块仓库验证凭据，再回到流水线比对；报错停在 Cloning into 且长时间不动，多半是在等待凭据输入。