Composer怎么做monorepo管理_单仓多包模式【核心】

Composer Monorepo 依赖本地 path 仓库实现，需严格对齐路径、包名、大小写及 repositories 顺序；改子包代码后 vendor 不更新，因 composer update 默认跳过 path 包，须用 --with-dependencies 或删 vendor 后重装。

先说一个核心事实：Composer 本身并不原生支持 Monorepo。我们常说的「单仓多包」模式，完全是依靠 repositories 配置项加上 path 类型仓库“拼凑”出来的。这种实现方式相当脆弱，路径、包名、大小写乃至配置顺序，但凡有一处对不上，你本地修改的代码就可能完全不会生效，而且 Composer 通常还不会报错，堪称静默的陷阱。

为什么改了子包代码，vendor里还是旧的

这大概是 Monorepo 实践中最常踩的坑了：你明明修改了 packages/my-sdk/src/Client.php，但执行完 composer dump-autoload 或 composer update 后，vendor/myorg/my-sdk 目录下的文件却纹丝不动。

• composer dump-autoload 这个命令，其职责仅仅是刷新类的自动加载映射，它不会触发任何包内容的同步。
• composer update 命令在默认情况下，会主动跳过所有 path 类型的本地包，除非你显式指定该包名并加上 --with-dependencies 参数。
• 最稳妥、一劳永逸的做法是：直接删除 vendor/myorg/my-sdk 这个目录，然后重新运行一次 composer install，强制 Composer 重建软链接。
• 如果你检查 vendor/myorg/my-sdk 发现里面是完整的文件复制，而不是一个指向本地目录的符号链接，那就说明 symlink 功能没有启用。这时，需要在根项目 composer.json 的 repositories 配置里为对应仓库加上 "options": {"symlink": true}。

repositories 怎么写才不被 packagist.org 覆盖

根项目 composer.json 中 repositories 数组的顺序，决定了 Composer 查找包的优先级，可谓一字千金。默认情况下，packagist.org 是一个隐式的、优先级很高的源。如果你没有禁用它，同时在 require 里写了诸如 "myorg/my-sdk": "^1.0" 这样的语义化版本约束，那么 Composer 会毫不犹豫地直奔远程仓库，去寻找已发布的 1.x 版本，从而完全忽略你本地的 packages/my-sdk 目录。

• 必须将 path 类型的仓库声明放在 repositories 数组的最前面。
• 必须显式禁用默认的 packagist.org 源，配置为：{"packagist.org": false}。
• 在 require 中引用本地包时，版本必须使用 "*@dev"、"dev-main" 或简单的 "*"，绝不能写成 "^1.0" 这类标准的语义化版本。
• 每次修改了 repositories 配置或子包自身的 composer.json 后，建议先运行 composer clear-cache，否则 Composer 可能会读取旧的缓存数据。

子包 autoload-dev 不生效怎么办

在根项目运行 phpunitautoload-dev 配置。

• 对于 path 类型的包，其 autoload-dev 配置默认是不启用的。即使子包自己的 composer.json 里写得再完整也无济于事。
• 解决方案是：必须在根项目的 composer.json 的 autoload-dev 区块中，手动添加子包测试文件的路径映射。例如："tests/MySdkTest.php": "packages/my-sdk/tests/"。
• 如果子包需要独立运行测试（例如在 CI 流水线中单独验证），那么它自身确实需要一份完整的 autoload-dev 和 require-dev 配置。但即便如此，在根项目调用时，仍然需要上述那条显式的配置。

通配路径和 symlink 的实际限制

别对 "packages/*" 这样的通配符路径抱有过高期望——它仅在 Composer 2.2 及以上版本被支持，并且要求每个匹配的目录下都必须存在合法的 composer.json 文件。而符号链接（symlink）在 Windows 上默认会失败，在 Linux/macOS 上也可能会因为文件系统的挂载参数而失效。

• "packages/*" 不是递归匹配，它无法覆盖像 packages/core/v2 这样的嵌套层级。对于深层子目录，必须显式地写出完整路径。
• Windows 用户必须以管理员身份运行终端，或者开启系统的“开发者模式”，否则创建符号链接（mklink）的操作会被系统拦截。
• Linux/macOS 用户如果发现软链接没有成功创建，首先应该检查 vendor/ 目录所在的文件系统是否挂载了 noexec 或 nosymfollow 这类限制性参数。
• 最省心的做法是：为所有 path 类型的仓库都统一加上 "options": {"symlink": true} 配置，不依赖系统或 Composer 的默认行为。

说到底，用 Composer 管理 Monorepo，本质上是一系列需要精确到字符的配置对齐工作：路径、包名、大小写、版本写法、数组顺序、缓存状态——漏掉其中任何一环，其外在表现都是“看起来安装成功了，但实际上根本没连上”。这种近乎苛刻的脆弱性，恰恰也是它实现轻量可控的前提。这里没有黑魔法，只有对细节的绝对掌控。