如何用 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 中声明：

标签： composer monorepo php js json 工具 ai