
运行时 class_exists() 检测不到就说明环境不匹配
插件在 Composer 1 和 2 中无法共用同一套初始化逻辑,最直接的缺口信号是 Class 'Composer\Plugin\Capability\CommandProvider' 找不到(v1 环境)或 Class 'Composer\Script\Event' 找不到(v2 环境)。这不是 autoload 问题,而是 Composer 自身加载插件类前就已根据 composer-plugin-api 版本拒绝激活。
验证方法很简单:在插件主类的 activate() 入口第一行加判断:
if (!class_exists('Composer\Plugin\Capability\CommandProvider') && !class_exists('Composer\Script\Event')) {
throw new \RuntimeException('Neither Composer 1 nor 2 plugin API is available');
}
如果这段代码直接 fatal error,说明 Composer 根本没走到你的 activate()——插件已被跳过或拒绝加载。
composer.json 里写 "^1.0 || ^2.0" 会直接安装失败
声明 "composer-plugin-api": "^1.0 || ^2.0" 看似合理,实则触发 Composer 自身校验拦截。v2 会因识别到 v1 的 API 元素而拒绝安装,v1 则解析不了 v2 的 capability 声明结构。
必须只写一个明确版本:
- 支持 PHP 7.2+ 老项目 →
"composer-plugin-api": "^1.1.0" - 要用
activate(Composer $composer, IOInterface $io)新签名 →"composer-plugin-api": "^2.2.0"
所谓“兼容”,只能靠代码里主动探测,不是靠 JSON 声明糊弄过去。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
插件 activate() 里 new 一个 v2 类就崩给 v1 看
v1 环境下,new MyCommandProvider() 这种写法只要出现在 activate()、__construct() 或静态初始化块中,就会立即 fatal error——根本等不到条件判断执行。
正确做法是把 v2 特有类的实例化完全隔离到独立方法,并仅在确认环境后调用:
public function activate(Composer $composer, IOInterface $io)
{
if (class_exists('Composer\Plugin\Capability\CommandProvider')) {
$this->registerV2Commands($composer); // 所有 new 都藏在这里
} else {
$this->registerV1Events($composer);
}
}
同时避免调用已移除方法,比如 Package::getNames()(v2 改为 getNamesWithStability()),这类调用即使加了 class_exists 也拦不住。
为什么 composer diagnose 不报插件兼容问题
composer diagnose 只检查基础环境和 lock 文件一致性,它不加载、不运行任何插件,因此完全无法发现插件 API 缺口。真正暴露问题的场景只有两个:
-
composer install或update时输出Plugin X is not compatible with Composer 2 - 插件该响应的事件(如
pre-install-cmd)完全没触发,且日志里无报错——静默失效比报错更难排查
复杂点在于:同一个插件包,可能在 CI 用 Composer 2 成功,在本地 Docker 用 Composer 1 却不生效,而两者 composer --version 输出看起来都“正常”。这时候得盯住实际运行插件的那台机器上 composer show composer/composer 返回的精确版本号,而不是凭印象判断。

















