Composer插件不工作主因是版本错配、配置未生效或被禁用；需核对Composer主版本与插件兼容性，确认extra.merge-plugin配置正确，检查是否启用插件及PHP扩展是否满足要求。
Composer 插件不工作，八成不是插件本身坏了，而是它和当前环境“说不上话”——版本错配、加载时机不对、配置没生效。先别急着换插件，按这几步查清楚再说。
确认插件与 Composer 主版本是否匹配
插件不是“一次安装，永久可用”，它严格绑定 Composer 主版本。比如 wikimedia/composer-merge-plugin 1.4.x 只支持 Composer 1.x；2.0.x 才支持 Composer 2.x。运行 composer --version 看清是 v1 还是 v2，再对照插件文档选对版本。
- Composer 1.x 用户：只能装插件 1.4.x 系列，
composer require wikimedia/composer-merge-plugin:^1.4 - Composer 2.x 用户：必须用 2.0.x，
composer require wikimedia/composer-merge-plugin:^2.0 - 混用会直接静默失效——插件注册了但不执行合并逻辑，
composer install像没它一样
检查插件是否真被加载（而非仅安装）
插件装进 vendor/ 不等于被启用。Composer 插件需在根项目的 composer.json 的 extra.merge-plugin 下显式声明配置，否则它连配置文件路径都读不到。
- 确保
extra字段存在且结构正确，不能漏掉"merge-plugin"二级键 -
include数组里的路径必须是相对于项目根目录的，比如"composer.local.json"要真存在，不能写成"./composer.local.json"或"config/composer.local.json"（除非路径确实如此） - 插件不校验路径是否存在，只按配置去读——路径错或文件空，它就默默跳过，不报错也不合并
验证插件行为是否被其他插件或命令绕过
某些 Composer 命令默认禁用插件，比如 composer install --no-plugins 或 CI 环境里设置了 COMPOSER_NO_PLUGINS=1。即使配置全对，插件也可能被主动关掉。
- 运行
composer install -v（加-v），观察输出里是否有Merging config from composer.local.json类提示——没有就说明没触发 - 检查是否在脚本中用了
--no-plugins，或全局环境变量COMPOSER_NO_PLUGINS被设为 1 - 部分插件（如
hirak/prestissimo）会接管网络请求，可能干扰依赖解析顺序，导致合并后的配置来不及参与求解
排查 PHP 版本与插件扩展要求冲突
插件自身也是 PHP 包，它的 composer.json 里可能声明了 php 或扩展依赖。比如某插件要求 ext-json，而你 CLI 的 PHP 关了 JSON 扩展，插件类就根本加载失败。
- 运行
php -m | grep json确认关键扩展已启用（json,mbstring,phar是高频依赖） - 用
composer show wikimedia/composer-merge-plugin查它要求的 PHP 版本范围，再比对php -v - 如果本地 PHP 是 8.0，但插件要求
^8.1，Composer 会跳过加载该插件，且不提示——它只报“包不兼容”，不报“插件未启用”
真正卡住的地方往往不是配置写错，而是插件加载链断在你看不见的位置：Composer 版本不认它、PHP 扩展缺位、或者命令行参数悄悄把它禁了。每一步都要用 -v 输出或 php -m 这类直白命令验证，而不是依赖“应该可以”。
