Composer如何处理子包的composer.json_Composer子包composer.json处理指南

Composer默认只读取当前工作目录的composer.json，子目录中同名文件被忽略；需用--working-dir指定路径执行安装，且子包类要手动在根目录autoload中映射并dump-autoload。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

如果你在项目里搞了子包，并且每个子包都有自己的composer.json，那可得留神了。Composer 并不会自动去“发现”这些子目录里的配置文件。除非你明确告诉它“去那个目录工作”，否则它一概视而不见——这几乎是所有人第一次尝试时都会踩的坑。

子目录的 composer.json 默认被完全忽略

道理很简单：Composer 只认当前你所在目录下的那个composer.json。你在packages/foo/composer.json里把依赖写得再详细，只要没切换到那个目录，或者没用专门的参数指定，Composer 就默认它不存在。其他同名文件？一律跳过处理。

• 典型症状：运行项目时，突然报Class not found，或者提示require_once(): Failed opening required 'vendor/autoload.php'。问题根源往往不是代码写错了，而是子包里的类压根没被注册到自动加载器里——因为 Composer 从头到尾就没“看见”那个子包。
• 这并非 Composer “不支持”子包，而是它没有“自动发现”的机制。它不像某些工具那样会扫描整个项目结构，也没有原生的 monorepo 模式。
• 一个直接的验证方法：如果你在项目根目录运行composer install，那么packages/foo/vendor/这个目录是不会被创建的，子包composer.json里列出的所有依赖，一条都不会被安装。

composer install --working-dir=packages/foo 是最直接的解法

不想频繁切换目录？有个更干净的办法。使用--working-dir参数，可以直接指定 Composer 的工作路径。一行命令，它就会在目标目录下执行完整的流程：读取配置、解析依赖、安装包、生成vendor/目录、编写自动加载文件。

• 路径格式要注意：这里用的必须是相对于当前目录的路径。像~或$HOME这种绝对路径不行，--working-dir=../foo这种向上回溯的路径也不行。必须是像packages/foo这样，从当前位置向下展开的路径。
• 执行成功后，所有依赖都会安装到packages/foo/vendor/下，与项目根目录的vendor/完全隔离，互不干扰。
• 在 CI/CD 脚本里，强烈推荐统一使用这个参数。这样可以避免使用cd命令切换目录后，忘记cd -回来，导致后续命令在错误路径下执行。
• 如果子包自己的composer.json里定义了自定义脚本（比如post-install-cmd），那么这些脚本也会在子包的上下文中被执行。当然，这仅限于子包自身的配置。

子包要被主项目加载，必须手动注册 PSR-4 并 dump-autoload

好了，子包的依赖装好了，但事情还没完。即使子包安装成功，它的类也不会自动出现在主项目的自动加载器里。想让主项目能“找到”子包的类，你还需要在根目录的composer.json里手动声明一下映射关系，然后重新生成自动加载文件。

• 具体操作是：打开项目根目录的composer.json，在"autoload"部分添加 PSR-4 映射。例如："Foo\": "packages/foo/src/"。
• 添加之后，务必在根目录运行composer dump-autoload。注意，不是在packages/foo/里运行，而是在项目根目录。
• 如果跳过这一步，你在主项目里尝试new Foo\SomeClass()，依然会收到熟悉的Class not found错误。因为之前用--working-dir安装子包，并不会自动触发根目录自动加载文件的更新。
• 如果子包里还包含测试类或者一些内部工具类，不希望被主项目生产环境加载，可以额外在"autoload-dev"中补充映射，比如"Foo\Tests\": "packages/foo/tests/"。

本地子包想被 require，必须配 repositories + require + @dev

更进一步，如果你希望主项目能像依赖 Packagist 上的包一样，通过composer require来引用这个本地子包，那么配置就要更完整一些。仅仅把子包放在packages/目录下是不够的，你需要让 Composer 能够“发现”它，并把它当作一个可安装、可锁定版本的依赖。

• 首先，在根目录composer.json的根层级，添加一个"repositories"配置项。类型（"type"）必须设为"path"，而"url"则是相对于这个composer.json文件的路径，例如："url": "packages/foo"。
• 其次，子包自己的composer.json里，必须有合法的"name"（例如"myorg/foo"）和"version"字段（或者使用"@dev"这样的版本标签）。
• 完成以上配置后，在根目录运行composer require myorg/foo *@dev，Composer 才会去匹配你配置的本地路径仓库。否则，它默认只会去 Packagist 上找。
• 开发小技巧：在repositories的配置里，可以加上"options": {"symlink": true}。这样 Composer 会创建符号链接而不是拷贝文件，你在子包里修改代码，主项目能即时生效，无需反复执行install。但切记，上线前一定要移除这个repositories配置块，否则部署很可能会失败。

最后，还有一个极易被忽略的“坑”：当项目里存在多个vendor/目录时，vendor/bin里的那些二进制文件可能会“打架”。比如，根目录和子包目录下可能装了不同版本的phpunit。而系统 shell 只认 PATH 环境变量里第一个找到的，你调用phpunit时，可能根本意识不到自己运行的是另一个版本的命令，结果自然让人困惑。这一点，在调试和测试时需要特别留意。