Composer如何做monorepo管理_Composer单仓多包组织方式【详解】
先说一个事实：Composer 本身并没有为 Monorepo 提供原生支持。目前所有能看到的“单仓多包”效果，本质上都是靠你在根目录下 composer.json 的 repositories 配置里，手动“骗”过 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 环境权限是否支持——漏掉任何一环，问题都不会即时暴露出来。往往要等到类找不到、代码不生效或测试跑不通的时候，才会意识到出了问题。所以，与其到时候花大把时间排查，不如一开始就把它控稳。