Composer 不管理 Git 子模块，需手动或通过脚本执行 git submodule update --init --recursive；可配置 post-install-cmd 钩子自动处理，或改用 --prefer-dist 跳过 git 操作。
Composer 本身不管理 Git 子模块，它只负责下载和安装包（通过 zip 或 git clone），子模块的初始化和更新需要你手动或额外配置完成。遇到“submodule 相关错误”，通常是因为目标包在 GitHub/GitLab 上使用了子模块，而 Composer 拉取时没触发 git submodule init && git submodule update。
确认问题是否真由 submodule 引起
先看报错关键词：比如 error: no such remote ref、fatal: No url found for submodule path、或提示某个路径是空目录但本该是子模块——这些大概率是 submodule 未加载导致的。可进入 vendor/xxx/package 目录，执行：
-
git status—— 看是否有未跟踪的子模块目录（显示为灰色文件夹） -
git submodule status—— 若输出为空或报错，说明子模块未初始化
让 Composer 自动处理 submodule（推荐方案）
在项目根目录的 composer.json 中添加脚本钩子，利用 Composer 的 post-install-cmd 和 post-update-cmd 自动运行子模块命令：
"scripts": {
"post-install-cmd": [
"@php -r \"if (is_dir('./vendor/xxx/package/.git')) { chdir('./vendor/xxx/package'); system('git submodule update --init --recursive'); }\""
],
"post-update-cmd": [
"@php -r \"if (is_dir('./vendor/xxx/package/.git')) { chdir('./vendor/xxx/package'); system('git submodule update --init --recursive'); }\""
]
}
⚠️ 注意：把 xxx/package 替换为实际出问题的包名；多个包就复制多行；确保系统已安装 Git 且在 PATH 中。
改用 dist 包绕过 git 操作（快速临时解法）
如果只是想跳过所有 git 行为（包括 submodule），强制 Composer 使用压缩包安装：
- 运行
composer install --prefer-dist或composer update --prefer-dist - 在
composer.json中全局设置："preferred-install": {"*": "dist"}
这样 Composer 会从 packagist 下载 zip 包而非 clone git 仓库，自然不涉及 submodule。但前提是该包在 Packagist 上有发布 dist 归档（绝大多数主流包都有）。
开发中长期维护建议
如果你自己是包作者，且必须用 submodule：
- 避免在
main或master分支直接依赖未发布的 submodule 提交；打 tag 前务必git submodule update --remote --merge并提交父仓库 - 在
README.md或CONTRIBUTING.md明确写清：克隆后需执行git submodule update --init --recursive - 考虑是否真需要 submodule——多数场景用独立包 + Composer 依赖更可靠、更易测试
基本上就这些。核心记住一点：Composer 不管 submodule，它只管包本身；子模块属于 Git 层的事，得靠你补上那一步，或者换种更“Composer 友好”的协作方式。
