子模块中运行 composer install 失败主因是路径污染或未初始化子模块；应进入子模块目录确认路径、清理残留 vendor/ 和 composer.lock 后执行；CI 中需显式运行 git submodule update --init --recursive。
子模块里运行 composer install 会失败？先确认工作目录和 vendor 路径
Git 子模块本质是独立仓库，composer.json 和 composer.lock 是它自己的。直接在子模块目录下执行 composer install 看似合理，但常因路径污染失败——比如父项目已加载 autoloader、或当前工作目录残留了父项目的 vendor/autoload.php。
实操建议：
- 进入子模块目录后，先用
pwd确认路径，确保不在父项目根目录下误操作 - 删掉子模块内可能残留的
vendor/和composer.lock（尤其从别人 clone 来的），再重新composer install - 不要在父项目根目录下用
composer install --working-dir=modules/foo这类方式——Composer 不保证跨目录 autoload 正确加载子模块的依赖
子模块依赖被父项目自动加载？小心 autoload 配置冲突
父项目 composer.json 的 "autoload" 或 "autoload-dev" 如果用了 "psr-4" 并覆盖了子模块命名空间（例如都用了 "App\"），会导致类加载错乱：父项目代码可能意外加载子模块里的同名类，或反之。
常见错误现象：
- 报错
Class 'FooBar' not found，但FooBar明明在子模块里定义了 - 调用子模块方法时实际执行的是父项目同名类里的逻辑
解决办法：
- 子模块必须声明独立的命名空间前缀，比如
"Vendor\Module\"，且不能与父项目重叠 - 父项目
composer.json中不要把子模块路径加进"autoload"——子模块应通过其自身vendor/autoload.php加载 - 若需在父项目中使用子模块功能，应在父项目
require子模块为包（见下一条）
想让父项目“真正依赖”子模块？别用 Git 子模块，改用 path repository
Git 子模块只是代码快照，不是 Composer 包。父项目无法通过 composer require 把子模块当依赖管理，也无法自动更新其 composer.lock 或处理版本约束。
仅从仓库的暂存文件生成 Git 提交消息。当用户要求 Codex 根据暂存更改、缓存差异、Git 索引或已通过 `git add` 添加的文件来编写、起草、创建或建议提交消息时使用；切勿代表用户执行提交操作。
正确做法是把子模块变成本地可安装的包：
- 在父项目
composer.json的"repositories"里加一个path类型源："repositories": [ { "type": "path", "url": "./modules/my-module" } ] - 然后在父项目中
composer require vendor/my-module:dev-main（注意版本需匹配子模块composer.json中的"version"或分支别名） - 这样 Composer 会软链接子模块到父项目的
vendor/，并参与整个依赖图解析、autoload 合并、版本约束检查
性能影响：本地 path 源不会走网络，安装极快；但 CI 环境需确保子模块路径存在，否则 composer install 直接失败。
CI/CD 中子模块 + Composer 自动化失败？关键在 git submodule update --init --recursive
很多 CI 流水线只执行 git clone，没拉取子模块内容，导致后续 composer install 找不到子模块的 composer.json，报错 Could not find a composer.json file。
必须显式初始化子模块：
- CI 脚本中，在
composer install前加一行：git submodule update --init --recursive - 如果子模块本身还有子模块（嵌套），
--recursive不可省略 - 某些 CI（如 GitHub Actions）默认不 fetch 子模块，还需配置
fetch-depth: 0或显式 checkout 子模块
容易被忽略的一点：子模块的 Git URL 是相对路径还是绝对路径？如果是 ../my-lib.git 这类相对地址，CI 工作目录结构不同会导致克隆失败——统一用 SSH 或 HTTPS 绝对地址更稳妥。
