要在 Git 拉取主项目时自动同步所有子模块，核心是通过 Git 内置的子模块命令实现，以下是完整的操作指南（覆盖「首次拉取」「已有项目更新子模块」「批量拉取」等场景）：

一、场景 1：首次拉取主项目（含子模块）

如果是第一次克隆主项目，直接用 --recurse-submodules 参数，可一键拉取主项目 + 所有子模块代码：

# 克隆主项目并自动初始化、拉取所有子模块
git clone --recurse-submodules <主项目仓库地址>

# 例如
git clone --recurse-submodules https://github.com/xxx/main-project.git

效果：克隆主项目后，会自动进入每个子模块目录，拉取对应分支的代码，无需手动操作。

二、场景 2：已克隆主项目，补拉子模块

如果已经克隆了主项目（但子模块目录为空），执行以下命令补全子模块：

# 进入主项目目录
cd 主项目文件夹

# 1. 初始化子模块（首次拉取子模块必须执行）
git submodule init

# 2. 拉取所有子模块的最新代码
git submodule update --remote

# 简化版（一步到位）： 初始化 + 拉取子模块，等同于 init + update
git submodule update --init --remote

--init：初始化子模块（创建 .gitmodules 中配置的子模块目录）；
--remote：拉取子模块的最新远程代码（而非主项目记录的固定提交版本）。

三、场景 3：拉取主项目更新 + 同步子模块更新

如果主项目已有更新（比如子模块的引用版本变了），需要同时拉取主项目和子模块的最新代码：

# 1. 拉取主项目的最新代码
git pull

# 2. 同步子模块到主项目指定的版本（推荐）
git submodule update

# （可选）若想让子模块也拉取各自远程的最新代码（而非主项目记录的版本）
git submodule update --remote

四、场景 4：批量拉取所有子模块的最新分支代码

如果子模块有多个，且想让所有子模块都切换到各自的默认分支（如 main/master）并拉取最新代码：

# 进入主项目目录
cd 主项目文件夹

# 批量更新所有子模块到远程最新版本
git submodule foreach git pull origin <子模块默认分支>

示例（子模块默认分支为 main）：

1	git submodule foreach git pull origin main

效果：遍历所有子模块，执行 git pull origin main，批量更新子模块代码。

五、关键说明 & 避坑点

子模块配置文件：主项目的 .gitmodules 文件记录了子模块的仓库地址和本地路径，若该文件缺失 / 错误，子模块无法拉取，需先检查该文件；
子模块的版本锁定：Git 子模块默认会锁定到主项目记录的固定提交版本（而非最新分支），若想拉取子模块最新代码，必须加 --remote 参数；
子模块权限问题：若子模块是私有仓库，需确保本地 Git 已配置对应的账号 / 密钥（如 SSH 密钥），否则拉取子模块会提示权限拒绝；
嵌套子模块：如果子模块中还有子模块，需加 --recursive 参数：

# 拉取主项目 + 一级子模块 + 二级子模块
git clone --recurse-submodules --recursive <主项目地址>
# 或已克隆项目补拉嵌套子模块
git submodule update --init --remote --recursive

总结

场景	核心命令
首次克隆主项目（含子模块）	`git clone --recurse-submodules <仓库地址>`
已克隆主项目，补拉子模块	`git submodule update --init --remote`
同步主项目 + 子模块更新	`git pull && git submodule update --remote`
批量更新所有子模块到最新分支	`git submodule foreach git pull origin main`

核心要点：

首次拉取用 --recurse-submodules 一键到位；
已有项目补拉子模块用 update --init --remote；
子模块默认锁定版本，需 --remote 拉取最新代码；
嵌套子模块需加 --recursive 参数。