Composer 默认不处理 Git 子模块，需手动初始化；解决路径缺失可改用 "path" 类型仓库，避免子模块未初始化导致的 composer.json 读取失败、autoload 错误及 vendor 脏状态等问题。
Composer install 时跳过 Git 子模块自动初始化
默认情况下，Composer 不会主动操作你的 Git 子模块——它既不拉取、也不更新 .gitmodules 里的内容。但如果你在 composer.json 的 repositories 中写了 "type": "vcs" 并指向一个含子模块的仓库，而本地又没提前 git submodule update --init，Composer 可能因无法读取子模块路径下的 composer.json 报错（比如 Could not find package xxx at version yyy）。
解决方法是：让 Composer 完全忽略子模块的存在，只把它当普通目录处理：
- 确保子模块目录下有合法的
composer.json（哪怕只是空壳），否则 Composer 会跳过整个路径 - 在根项目
composer.json中，用"path"类型仓库显式声明子模块路径，例如："repositories": [ { "type": "path", "url": "./modules/my-submodule" } ] - 这样 Composer 就不会尝试走 Git 协议去解析它，也绕开了子模块未初始化导致的路径缺失问题
用 Composer require 引入含子模块的私有包时的权限陷阱
当你 composer require vendor/package，而该包本身使用了 Git 子模块（比如依赖某个私有 C 扩展的 PHP 封装），Composer 默认只 clone 主仓库，子模块不会被拉取——结果就是安装后缺文件、autoload 失败、扩展编译报错。
常见错误现象包括：Class 'VendorPackageSomeClass' not found，或 ext/xxx not enabled 却找不到对应源码目录。
可行方案有三个：
- 要求包维护者发布时把子模块内容打平进主仓库（不推荐，污染历史且难维护）
- 在 CI 或部署脚本中，
composer install后补一句git submodule update --init --recursive（注意：必须在项目根目录执行，且要求目标机器有 Git 和对应仓库权限） - 改用
"package"类型仓库手动定义，把子模块内容打包进 dist ZIP，并在"dist"字段里指定可直接下载的归档地址（适合私有 Satis 或 Artifactory 环境）
vendor 目录里混入 Git 子模块导致 git status 脏的问题
有些团队会把第三方包 fork 后加子模块再 require，结果 vendor/vendorname/pkg 下多出 .gitmodules 和 .git，每次 git status 都显示 “untracked files” 或 “modified: vendor/...”，CI 也可能因检测到未提交变更而失败。
根本原因：Composer 默认保留 VCS 元数据（除非你设了 "prefer-dist": true）。但即使如此，如果包是通过 "path" 或 "package" 加载的，仍可能带入 .git。
安全做法：
- 永远在
composer.json顶层加上："config": { "preferred-install": { "*": "dist" }, "autoloader-suffix": "YourApp" } - 对已污染的
vendor，运行：find vendor -name '.git' -type d -exec rm -rf {} +（慎用，确认没改 vendor 内代码） - CI 环境建议加检查：
git status --porcelain vendor/ | grep -q '.' && exit 1，防误提交
子模块路径与 Composer autoload 的冲突处理
当子模块目录被 autoload["psr-4"] 映射，且该路径又恰好是 Git 子模块的挂载点（如 "My\Sub\": "modules/submodule/src/"），Composer dump-autoload 可能生成错误的 classmap 或忽略该路径——尤其在子模块未初始化时，modules/submodule/src/ 根本不存在。
关键点在于：Composer 的 autoloader 不校验路径是否存在，只按配置扫描。所以一旦子模块没拉下来，dump-autoload 会静默跳过，后续运行时报 Class not found。
应对方式：
- 在
composer.json的"autoload"段里，避免直接映射子模块路径；改用符号链接（ln -sf ../modules/submodule/src ./src/Submodule），再映射"My\Sub\": "src/Submodule/" - 或用
"files"加载方式替代 PSR-4，显式 require 子模块里的引导文件（适合小范围工具类） - 开发前加个 Makefile 或 pre-install hook，检查
test -d modules/submodule/src，不满足就 abort
git submodule init，除非你把它写进 scripts 里，且确保每台机器都有 Git 凭据。 
