子模块目录为空、VSCode不显示代码、SCM面板无状态，是因为Git未拉取子模块内容；需在主仓库根目录执行git submodule update --init --recursive补救，并用多根工作区（.code-workspace）使子模块出现在SCM下拉菜单。
子模块目录空着、VSCode里看不到代码、SCM面板不显示子模块状态——不是VSCode坏了，是Git根本没把子模块代码拉下来。
克隆后子模块目录是空的，怎么补救
直接 git clone 含子模块的仓库，子模块目录默认为空（甚至在 VSCode 里显示为灰色图标），因为 Git 不会自动初始化和检出子模块。
- 进主仓库根目录（
pwd确认路径，别在子模块里敲） - 运行
git submodule update --init --recursive：一步完成初始化、拉取、递归处理嵌套子模块 - 如果已执行过
git submodule init但漏了--recursive，而子模块里还有子模块（比如 A → B → C），C 仍为空——必须补上--recursive - VSCode 集成终端（
Ctrl + `）完全可用，但路径错就报fatal: not a git repository
子模块代码更新了，VSCode里却看不到新文件
VSCode 不会主动读取子模块目录下的 .git 文件（它是个文本文件，内容是 gitdir: ../.git/modules/xxx），所以不会自动刷新文件树或高亮变更。
- 先进入子模块目录：
cd path/to/submodule - 手动拉最新代码：
git pull origin main（或你实际跟踪的分支） - 回到主项目根目录：
cd .. - 运行
git status，你会看到类似modified: path/to/submodule (new commits) - 必须
git add path/to/submodule && git commit -m "update submodule"，否则新提交对协作者不可见
怎么让子模块也出现在VSCode的SCM面板下拉菜单里
默认 SCM 只显示主仓库，子模块因 .git 是文件而非文件夹，被 Git 扩展跳过识别。
- 新建一个空文件夹，用 VSCode 打开
- 执行
File → Add Folder to Workspace…，分别添加主项目和各子模块所在文件夹 - 保存为
my-project.code-workspace文件 - 之后双击该文件打开，SCM 顶部就会出现下拉框，可切换查看主项目或任一子模块的
git status - 注意：每个文件夹仍是独立 Git 操作，VSCode 不会帮你批量提交或推送
为什么 git submodule update 有时没反应
常见原因是子模块尚未注册到本地配置 —— .gitmodules 只是声明，.git/config 还没写入对应条目。
-
git submodule update前必须先git submodule init，否则命令静默失败 - 更安全的做法永远是
git submodule update --init --recursive，避免漏掉初始化步骤 - 如果子模块 URL 已变更（比如 fork 后改了 remote），先运行
git submodule sync再update，否则可能拉错仓库 - CI 场景建议加
--jobs=4加速：git submodule update --init --recursive --jobs=4
子模块真正的复杂点不在命令本身，而在于「父仓库只存 commit hash，不存分支逻辑」——你进子模块 git checkout dev，父仓库立刻显示 modified；但别人 git pull 后不会自动切到 dev，只会检出那个 hash 对应的快照。这个隐含契约，容易被忽略。
