如何用 Composer 管理一个包含多个子模块（monorepo）的项目？

Composer 可通过合理配置支持 monorepo：各子模块独立 composer.json，根目录 composer.json 用 path repository 管理本地依赖、统一开发工具与脚本，避免 autoload 冲突，无需插件即可实现高效协同。

Composer 本身不原生支持 monorepo，但可以通过合理配置和约定，让 Composer 在多子模块项目中协同工作。关键不是强行让 Composer “管理 monorepo”，而是让每个子模块保持独立的 composer.json，同时统一依赖版本、共享开发工具，并避免重复安装或冲突。

每个子模块单独定义 composer.json

在 monorepo 中，每个可复用的包（如 packages/utils、packages/api-client）都应有自己完整的 composer.json，声明其名称、版本（可用 dev-main 或 dev-develop）、依赖和自动加载规则。

例如 packages/utils/composer.json：

{
  "name": "myorg/utils",
  "type": "library",
  "autoload": {
    "psr-4": { "MyOrg\\Utils\\": "src/" }
  },
  "require": {
    "php": "^8.1"
  }
}

这样它就能被其他模块或外部项目通过 Composer 正常 require 和 autoload。

根目录放主 composer.json 管理开发依赖与脚本

根目录的 composer.json 不用于发布，而是作为“工作区入口”：集中管理所有开发工具（如 PHPUnit、PHPStan、PHP-CS-Fixer）、统一配置（如 minimum-stability），并定义跨包命令。

常用做法包括：

• 把 require-dev 设为全仓库共用的工具链
• 用 repositories 指向本地 packages 目录，让 Composer 能解析未发布的子模块
• 用 scripts 定义一键命令，比如 "test:all": "composer exec -- phpunit --configuration packages/*/phpunit.xml"

用 path repository 实现本地子模块互引用

在根 composer.json 中声明：

"repositories": [
  {
    "type": "path",
    "url": "./packages/*"
  }
]

然后在 packages/api-client/composer.json 中就可以直接写：

"require": {
  "myorg/utils": "dev-main"
}

Composer 会自动软链接 packages/utils 到 vendor/myorg/utils，修改即实时生效，无需反复 composer update。

避免自动加载冲突与版本混乱

多个子模块可能共用同一命名空间前缀（如 MyOrg\*），需确保：

• 各子模块的 autoload 路径不重叠（例如 packages/utils/src/ vs packages/api-client/src/）
• 根 composer.json 不声明全局 autoload —— 否则会干扰子模块自己的加载逻辑
• 上线或打包时，用 composer install --no-dev 并指定目标子模块目录，而非运行在根目录

CI/CD 中建议对每个子模块单独执行 composer install + composer test，而不是全局一把梭。

基本上就这些。不需要魔改 Composer，也不用第三方插件——靠路径仓库、清晰的 autoload 划分和脚本编排，就能让 monorepo 和 Composer 配合得干净又可控。