Composer如何做monorepo管理_Composer单仓多包组织方式【详解】

先说一个事实：Composer 本身并没有为 Monorepo 提供原生支持。目前所有能看到的“单仓多包”效果，本质上都是靠你在根目录下 composer.json 的 repositories 配置里，手动“骗”过 Composer——告诉它“这几个目录就是合法的包，直接当本地源用”。而且关键在于，路径、包名、版本（必须写 @dev）、以及 soft link 选项，这四样东西必须严丝合缝。错一个字符，Composer 不会提示你配置有问题，而是静悄悄地绕开本地路径，直接去远程 Packagist 上拉包——等到发现代码不生效，排查成本早就上去了。

path 类型仓库必须写在根 composer.json 的 repositories 里

子包自己哪怕有再规范、再完善的 composer.json，Composer 也完全不会多看一眼。它只盯着根目录下发号施令的那个 composer.json，只认 repositories 数组里声明的那些路径。如果没有在根配置里注册，子包写得再认真也没用。

具体操作上，有几点需要特别留意：

• url 字段里写的路径，必须是相对于根 composer.json 的精确相对路径。比如 "packages/logging"，不要加 ./，也不要用绝对路径——后者会导致协作者的开发环境直接崩掉。
• Composer 早期版本不支持通配符递归匹配。虽然 Composer 2.2 之后可以有限地使用 "packages/*" 这样的写法，但前提是每个子目录下都必须有合法可用的 composer.json，并不是无脑适配所有场景。
• 如果你的子包位于 services/core/v2 这样的嵌套结构里，那就只能老老实实逐条添加：{"type":"path","url":"services/core/v2"}。别指望 Composer 能自动扫描发现它们。
• 每次修改 repositories 后，强烈建议执行一次 composer clear-cache。否则它可能还在读取旧的缓存信息，导致路径不生效，排查起来会很头疼。

require 的包名必须和子包 composer.json 的 name 字段完全一致

这里是一个极易踩雷的细节。大小写、连字符、斜杠方向，全部严格区别。比如 "acme/utils" 和 "Acme/Utils" 就是完全不同的两个包，更别提 "acmeutils" 这种写法。一旦写错一个字符，Composer 不会报错，而是直接放弃本地路径，转头去远程仓库寻找同名的包——这是 Monorepo 开发中最隐蔽的坑之一：代码没有报错，但加载到的其实是端上的旧代码。

• 子包 composer.json 中必须有一个非空的 name 字段，格式必须是 "vendor/name"，比如 "myorg/http-client"。
• 根项目的 require 中对应该包的键名，必须和子包的 name 完全一致，并且不能写版本约束，比如 "^1.0"。统一使用 "\*@dev" 或 "@dev" 就好，这样 Composer 才会优先使用本地源。
• 如果子包自身依赖了另一个本地包，那这个被依赖的包也必须同时出现在根 repositories 列表里。否则，Composer 在解析依赖树时会因为找不到包而直接失败。

符号链接不是默认行为，需要显式启用并确认环境支持

正常情况下，你期待的是 vendor/myorg/http-client 这个目录，通过软链接指向 packages/http-client，以便代码实时同步。但如果你发现它是直接将代码复制了一份过去，那说明软链接没有生效，Composer 已经退化到了 copy 模式。

• 必须在 repositories 对应的条目里显式加上 "options": {"symlink": true}，强制启用软链。2026 年主流的 Composer 版本都已经支持这个特性，但默认情况下它不会开启。
• Windows 用户需要尤其注意：要么以管理员身份运行终端，要么提前开启系统的“开发者模式”，否则 mklink 命令会被直接禁用。
• Linux 和 macOS 用户如果发现仍然失败，可以检查一下 vendor/ 目录所在的文件系统是否挂载了 noexec 或 nosymfollow 选项。
• 一旦软链接建立成功，你直接在 packages/http-client/src/Client.php 里改代码，主项目那边会立刻同步看到最新内容——这才是 Monorepo 本地开发的真正效率所在，千万别被 dump-autoload 这个命令迷惑了。

子包修改后 vendor 不更新？不要依赖 dump-autoload

composer dump-autoload 只负责刷新自动加载映射，它完全不触发包内容的同步。所以你改了子包的代码，vendor/ 目录里保存的还是旧文件——Composer 把 path 包当作“已安装”状态，不会主动去拉取新版本。

• 正确的做法是执行 composer update myorg/http-client --with-dependencies。一定要加上 --with-dependencies，否则它可能跳过依赖链的更新。
• 更彻底一点的方案是：先手动删除 vendor/myorg/http-client 整个目录，然后重新执行 composer install 或 composer update。
• 如果子包配置了 autoload-dev，而且需要被根项目的测试用例（比如 PHPUnit）调用到，那就必须在根 composer.json 的 autoload-dev 中显式加入该路径。举个例子："MyOrg\HttpClient\Tests\": "packages/http-client/tests/"。子包自己定义的 autoload-dev，对根项目来说是无效的，它只适用于子包独立运行时。

说实话，整个配置过程的技术难度并不大，真正的难点在于：每一个环节都依赖“完全一致”这个前提。路径拼写、包名字符大小写、name 字段是否存在、autoload 前缀的范围是否准确、symlink 环境权限是否支持——漏掉任何一环，问题都不会即时暴露出来。往往要等到类找不到、代码不生效或测试跑不通的时候，才会意识到出了问题。所以，与其到时候花大把时间排查，不如一开始就把它控稳。