composer如何安装包含submodules的包_composer子模块处理方法【指南】

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 的所有语义。