Composer只读当前工作目录的composer.json，子目录文件默认被忽略；必须通过repositories配置path类型仓库、require中精确匹配name和版本、子包autoload正确声明三者协同，才能使子目录包被识别和加载。
Composer 本身不拆包，也不管理“内部依赖”的物理结构——它只认已发布的包。所谓“管理复杂项目的内部依赖”，本质是把子目录变成合法 Composer 包，并让主项目能正确发现、解析、加载它们。没走通这三步，composer install 就只会忽略那些 packages/xxx/composer.json。
为什么 composer install 不自动识别子目录里的 composer.json
Composer 永远只读当前工作目录下的 composer.json，其他同名文件完全不可见。你放一百个 composer.json 在 modules/ 或 packages/ 里，只要没在根目录 repositories 中显式声明，Composer 就当它们不存在。
- 错误现象：
composer install后vendor/里没有你的myapp/user-service，但目录明明存在且有合法composer.json - 根本原因：主项目的
composer.json缺少"repositories"配置，或url路径写错（比如用了../跨出项目边界） - 验证方式：运行
composer validate，如果报Invalid repository type "path"或路径无法解析，就是配置问题
怎么配置 path 类型仓库才真正生效
path 仓库不是“告诉 Composer 去哪找代码”，而是“告诉 Composer：这个本地目录是一个可安装的包，按它的 composer.json 解析”。它必须满足三个硬条件：
-
url必须是相对于主项目根目录的路径，例如"url": "packages/user-service"，不能是"url": "../user-service" - 子目录里的
composer.json必须含"name"字段，且值与主项目require中写的完全一致，比如"myapp/user-service": "*" -
"*"默认匹配dev-main或dev-develop分支；如需固定到某次提交，得写成"myapp/user-service": "dev-main#abc123"
autoload 冲突和命名空间覆盖怎么避坑
多个子包共用同一个 PSR-4 前缀（比如都注册 "App\"）会导致自动加载器只认最后一个——这不是 Composer 的 bug，是 PHP 自动加载机制的确定性行为。
- 每个子包的
composer.json中autoload.psr-4必须用唯一前缀，例如"MyApp\UserService\"→"src/"，"MyApp\OrderService\"→"src/" - 主项目根目录的
composer.json可以统一映射，但不能覆盖子包自己的 autoload；否则子包内类在主项目中可能找不到 - 新增子包后，必须运行
composer dump-autoload，否则新命名空间不会写入vendor/autoload.php
拆包后怎么确保 CI 和部署不掉链子
本地用 path 仓库调试很顺，但 CI 构建时若还依赖这些本地路径，就会失败——因为构建机上根本没有 packages/user-service 目录。
- 生产环境必须切换到真实包源：要么发布到私有 Packagist，要么在 CI 的
composer.json中临时替换repositories为{"type":"composer","url":"https://your-private-repo.com"} - CI 脚本里禁止出现
composer update；必须用composer install --no-dev --no-interaction --optimize-autoloader - 所有子包必须打语义化标签（如
v1.2.0），主项目require中避免用"*"，改用"^1.2"或具体版本，否则 lock 文件会锁定 dev 分支，不可重现
最常被跳过的一步：子包的 composer.json 里没写 "type": "library" 或 "type": "symfony-bundle"，导致某些工具（如 Flex recipes）无法识别其用途；类型字段虽非强制，但在 monorepo 场景下是明确语义的关键标记。
