Composer 不支持自动克隆 Git 子模块，因其职责限于 PHP 依赖管理，子模块属 Git 协作约定；可通过 post-install-cmd/post-update-cmd 脚本或 path 类型仓库手动处理。
Composer 本身不支持自动克隆 Git 子模块（submodules），即使你用 git clone --recursive 手动拉下源码，composer install 或 composer update 也不会触发子模块初始化。这是设计使然，不是 bug。
为什么 composer 不处理 submodules
Composer 的核心职责是管理 PHP 依赖的版本、自动加载和包分发，它把代码获取（如从 Packagist、Git、HTTP）交给底层 VCS 驱动（比如 GitDownloader），而这些驱动默认调用的是 git clone --no-checkout + git checkout，跳过了 --recursive 和后续的 git submodule update --init 步骤。
- 子模块属于 Git 的协作约定，不是 PHP 包规范的一部分
- 子模块路径、分支、是否递归更新等行为难以统一建模进
composer.json - 安全考虑：自动执行子模块拉取可能引入不可控外部依赖
手动补全 submodule 的两种可靠方式
如果你必须使用含 submodule 的包（比如某私有 SDK 依赖了另一个 Git 仓库的工具库），推荐以下任一方案：
- 在项目根目录的
composer.json中添加scripts，利用 Composer 的post-install-cmd和post-update-cmd钩子执行子模块初始化 - 改用
path类型仓库 + 本地 Git 管理，把整个含 submodule 的仓库当作本地开发源，由你控制git submodule update --init --recursive
第一种更通用；第二种适合深度定制或 CI/CD 中需完全可控的场景。
在 composer.json 中注入 submodule 初始化脚本
在你的项目 composer.json 的 scripts 字段里加入：
{
"scripts": {
"post-install-cmd": [
"@php -r \"if (is_dir('.git')) { system('git submodule update --init --recursive 2>/dev/null || true'); }\""
],
"post-update-cmd": [
"@php -r \"if (is_dir('.git')) { system('git submodule update --init --recursive 2>/dev/null || true'); }\""
]
}
}
说明：
- 用
@php -r是为了兼容 Windows 和 Unix，避免 shell 脚本跨平台问题 -
is_dir('.git')判断当前是否为 Git 工作区，防止在生产部署（无 .git）时出错 -
2>/dev/null || true抑制 submodule 不存在时的报错，避免中断 composer 流程 - 该脚本只对通过
vcs方式安装的包生效（即"type": "vcs"或直接指定 Git URL），对 dist 安装（zip/tar）无效 —— 因为 dist 包里本就不含 .git 和 submodule 元信息
使用 path repository 替代 vcs 并自行维护 submodule
如果你控制该包的源码（例如公司内私有组件），更稳妥的做法是：
- 把含 submodule 的仓库完整 clone 到本地某个路径（如
./packages/my-sdk） - 在项目
composer.json中声明path类型仓库：
{
"repositories": [
{
"type": "path",
"url": "./packages/my-sdk"
}
],
"require": {
"vendor/my-sdk": "dev-main"
}
}
然后每次更新 submodule 时，手动进入 ./packages/my-sdk 执行：
git pull git submodule update --init --recursive
再运行 composer update vendor/my-sdk 即可。这种方式绕开了 Composer 对 Git 操作的限制，也便于调试 submodule 内容。
真正麻烦的不是“怎么让 submodule 出来”，而是确认 submodule 是否被正确检出、是否与主包 commit 兼容、以及 CI 环境中是否启用了 --recursive clone。别指望 composer install 自动搞定 Git 的所有语义。
