composer install不支持多模块自动识别，只读取当前目录composer.json；多模块需通过path仓库软链或composer-merge-plugin合并配置实现，前者用于本地联调，后者需正确配置include路径并手动dump-autoload。

composer install 本身不支持多模块自动识别

它只认当前目录下的 composer.json，不会递归扫描子目录或自动合并多个配置文件。所谓“多模块项目”，必须靠人工结构设计来适配——要么用 path 类型仓库把模块当本地包引入，要么用 composer-merge-plugin 合并分散的 JSON 配置。

用 path 类型仓库让 composer install 软链模块代码

这是本地开发最轻量的做法，composer install 会把指定路径下的模块目录软链接进 vendor/，改代码立刻生效。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

• 每个模块目录（如 modules/user）必须有合法 composer.json，含 "name" 字段（如 "myorg/user"）和 "autoload" 映射
• 主项目 composer.json 的 repositories 里加：

  { "type": "path", "url": "./modules/user" }

• require 段写 "myorg/user": "dev-main"（分支名要匹配，dev- 前缀不能漏）
• 执行 composer install 后，vendor/myorg/user 是指向 modules/user 的软链接，不是复制
• 上线前必须删掉 repositories 中的 path 条目，换成私有仓库地址，并提交更新后的 composer.lock

用 composer-merge-plugin 合并多环境或多模块配置

这个插件能让 composer install 加载额外 JSON 文件里的依赖和 autoload 规则，但要注意版本和路径写法。

• 必须装 composer-merge-plugin（不是 wikimedia/composer-merge-plugin），否则 2.2+ 版本会静默失败
• extra.merge-plugin.include 必须写在顶层 composer.json，路径以 ./ 开头，例如："./modules/payment/composer.json"
• 被合并的 JSON 文件顶层必须是对象（{}），不能是数组（[]），否则报 JSON decode error
• 改完被合并的文件后，composer install 不会自动刷新 autoloader，必须手动跑 composer dump-autoload
• 多个文件按 include 数组顺序合并，后出现的同名键会覆盖前面的

生产部署时 composer install 的关键约束

多模块 ≠ 多 vendor 目录，也 ≠ 多入口自动加载。生产环境只认标准流程：一个项目、一个 composer.json、一个 vendor/、一次 composer install --no-dev。

• path 和 merge-plugin 都只是开发阶段辅助手段，CI/CD 流水线或 Docker 构建时它们会失效——因为路径不存在或插件未启用
• 真正可交付的模块，必须发布为带语义化版本的独立包，走私有 Packagist 或 Git Tag，然后在各项目中 composer require
• composer install 在生产机上运行前，确保 composer.lock 已提交且内容稳定；跳过 --no-dev 可能引入测试工具类，导致线上报错或性能下降
• 不要试图共享 vendor/ 目录或用 composer global 装业务模块——autoload 路径硬编码，Class not found 是必然结果

真正卡住人的从来不是命令怎么敲，而是没想清楚：模块到底是临时联调用的，还是长期复用的。前者用 path，后者必须发包。混淆这两者，composer install 就永远在本地能跑、上线就崩。