使用 Composer Merge Plugin 可将多个配置文件合并到主 composer.json 中，1. 先在 require 中添加 wikimedia/composer-merge-plugin；2. 在 extra 中配置 include 指定要合并的文件路径；3. 外部文件仅包含需合并的部分，如依赖或自动加载设置；4. 支持通配符和递归合并，可通过 merge-dev、merge-extra-deep 等选项控制合并行为，提升大型项目可维护性。

在大型项目中，composer.json 文件可能变得非常庞大且难以维护。为了解决这个问题，可以使用 Composer Merge Plugin 将多个配置文件合并到主 composer.json 中。这样可以把不同模块或环境的依赖拆分到独立文件中，提升可读性和可维护性。

安装 Composer Merge Plugin

要在项目中使用该插件，需先将其添加到项目的根目录下的 composer.json 中：

{
    "require": {
        "wikimedia/composer-merge-plugin": "^2.0"
    }
}

执行 composer install 安装插件后，它会自动激活并查找需要合并的额外配置文件。

配置要合并的文件

在 composer.json 的 "extra" 字段中指定哪些外部配置文件需要被合并：

{
    "extra": {
        "merge-plugin": {
            "include": [
                "configs/dependencies.json",
                "modules/*/composer.json"
            ]
        }
    }
}

上面的配置表示：

• 合并 configs/dependencies.json 中的内容
• 合并 modules/ 目录下所有子目录中的 composer.json 文件

编写外部配置文件

外部文件结构与标准 composer.json 类似，但只包含你需要合并的部分。例如 configs/dependencies.json：

{
    "require": {
        "monolog/monolog": "^2.0"
    },
    "autoload": {
        "psr-4": {
            "App\\Logging\\": "src/Logging/"
        }
    }
}

这些配置会被合并进主 composer.json 的对应字段中。如果存在相同键名（如重复的 require 包），后面的会覆盖前面的，具体行为取决于类型和插件设置。

高级选项（可选）

你可以在 merge-plugin 配置中调整合并行为：

"merge-plugin": {
    "include": [
        "configs/*.json"
    ],
    "recurse": true,
    "replace": false,
    "merge-dev": true,
    "merge-extra": true,
    "merge-extra-deep": true
}

说明：

• recurse：是否递归处理被包含文件中的 include 指令
• replace：设为 true 时，同名属性将完全替换而非合并
• merge-dev：是否合并 require-dev 中的内容
• merge-extra-deep：深度合并 extra 字段，避免简单覆盖

基本上就这些。通过 Composer Merge Plugin，你可以轻松管理复杂的依赖结构，把配置按功能或模块拆分，让项目更清晰、协作更高效。不复杂但容易忽略的是路径通配符和合并优先级，建议先小范围测试再推广使用。