composer 2.4+才实验性支持workspaces，但仅限本地路径映射；实际monorepo方案依赖path repository+minimum-stability+prefer-stable手动编排，需显式声明repositories、统一version、禁用project type，并用replace/conflict强制依赖对齐，autoload-dev须根目录显式配置。
composer.json 的 workspaces 不是原生支持的
Composer 官方直到 2.4+ 才实验性引入 workspaces，但仅限于本地路径映射，不解决跨服务依赖版本对齐问题。你看到的“monorepo + workspaces”方案，实际是靠 path repository + minimum-stability + prefer-stable 组合实现的——不是语法糖，是手动编排。
常见错误现象：composer install 报错 Could not find package xxx in a version matching yyy，本质是子包未被正确注册为本地源。
- 必须在根
composer.json中显式声明"repositories"，类型为"path"，指向各服务目录（如"packages/*"） - 每个子服务的
composer.json必须有明确"version"（如"dev-main"），否则 path repo 无法解析 - 根项目不能设
"type": "project"，否则 Composer 会跳过 workspace 包的 autoload 合并
如何让所有微服务强制使用同一版 symfony/http-foundation
靠 require 锁死没用——子服务各自 composer.json 里写的版本范围会覆盖根约束。真正生效的是根项目的 "replace" + "conflict" 双保险。
使用场景：当你升级了基础组件但某个旧服务还没适配，又不能让它拖慢整体节奏时。
- 在根
composer.json的"replace"中列出所有需统管的包，如"symfony/http-foundation": "6.4.0" - 同时加
"conflict"阻止子服务声明冲突版本："symfony/http-foundation": ">=7.0.0" - 子服务的
composer.json里删掉这些包的require条目，改由根项目统一提供 - 执行
composer update --with-all-dependencies才能穿透更新子包依赖树
autoload-dev 在 workspace 下容易漏加载
子服务的测试类、fixture 或 Tests/ 目录默认不会被根 autoloader 扫描，composer dump-autoload 也不自动合并。结果就是 phpunit 找不到测试类，或者 phpstan 报未定义符号。
性能影响：手动加几十个 psr-4 映射会让 vendor/autoload.php 初始化变慢，但比运行时 class not found 强。
- 根
composer.json的"autoload-dev"必须显式包含所有子服务的测试命名空间，例如："MyApp\ServiceA\Tests\": "packages/service-a/tests/" - 子服务自己的
"autoload-dev"会被忽略，别白写了 - 改完后必须运行
composer dump-autoload --optimize-autoload，否则 PSR-4 映射不生效
CI 中 composer install 失败率高，常卡在 path repo 解析
本地好好的，CI 上报 Package xxx could not be found in any version，大概率是路径通配没展开或权限问题。Docker 构建尤其明显。
兼容性影响：GitHub Actions 默认 checkout 是 shallow clone，git describe --tags 类命令失效，导致 dev-main 这种版本号解析失败。
- CI 脚本开头加
git fetch --prune --unshallow || git fetch --prune确保 tag 可见 - 避免用
"packages/*"这种 shell 通配——CI 环境可能不支持，改用明确路径列表 - 在 CI 的
composer install前加composer config --global repositories.packages.type path预注册，防止并发解析竞争
最易被忽略的点：子服务的 composer.json 里如果用了 "require-dev" 引用根项目中不存在的包（比如本地才装的 phpstan 插件），整个 workspace 的 install 就会静默失败——它不报错，只是跳过那个包，然后 autoload 缺失。得用 composer show --tree 手动核对依赖链。
