Composer 不会自动检测插件兼容性,而是严格校验 composer-plugin-api 版本声明是否匹配当前版本:v1 要求 "^1.1.0" 且 activate 为三参数,v2 要求 "^2.2.0" 且为两参数并支持 capability;声明 "^1.0 || ^2.0" 会导致 v2 解析失败,根本无法安装。

Composer 安装时如何判断插件是否兼容
Composer 不会“自动检测”插件兼容性,而是直接校验 composer-plugin-api 版本声明是否匹配当前运行版本。不匹配就拒绝安装或激活,根本不会进入插件代码逻辑。
常见错误现象:Plugin X is not compatible with Composer 2 或 Class 'Composer\Plugin\Capability\CommandProvider' not found(在 Composer 1 环境下)。
- Composer 1 只认
"composer-plugin-api": "^1.1.0",且只支持activate(Composer $composer, IOInterface $io, ArrayObject $composerConfig)三参数签名 - Composer 2 要求
"composer-plugin-api": "^2.2.0",activate()是两参数,且新增了CommandProvider、Installer等 capability 类 - 若在
composer.json的require中写"composer-plugin-api": "^1.0 || ^2.0",Composer 2 会直接报错退出,连解析都失败
为什么不能靠 composer-plugin-api 版本声明实现双版本兼容
这不是语义化版本能覆盖的场景——v1 和 v2 的插件机制是两套不兼容的运行时模型。
关键差异点:
-
Event类路径不同:Composer\Script\Event(v1) vsComposer\Plugin\Event(v2) - 插件激活时机和上下文对象结构完全不同,v2 的
Composer实例不再暴露getPackage()等 v1 方法 - v2 引入 capability 模式(如
CommandProvider),v1 根本没有这些类,class_exists('Composer\Plugin\Capability\CommandProvider')在 v1 下恒为false
所以所谓“兼容”,只能靠插件自己在运行时探测环境,而不是指望 Composer 帮你桥接。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
插件内如何做 Composer 1/2 运行时降级
核心动作是在插件主类的 activate() 入口处,用 class_exists() 和 method_exists() 分支加载逻辑,而非提前声明依赖。
典型做法:
- 先判断
class_exists('Composer\Plugin\Capability\CommandProvider')—— 若存在,走 v2 capability 注册路径 - 否则 fallback 到 v1 的事件监听注册方式(如
$composer->getEventDispatcher()->addListener('post-autoload-dump', [...])) - 对
IOInterface的使用也要检查方法是否存在,例如$io->writeError()在 v1 中不存在,得回退到$io->write() - 避免在类定义顶层引用 v2 专属类,否则 v1 加载时直接
Fatal error: Class not found
示例片段(非完整类):
public function activate(Composer $composer, IOInterface $io)
{
if (class_exists('Composer\Plugin\Capability\CommandProvider')) {
// v2 路径:注册 capability
return;
}
// v1 路径:绑定事件
$dispatcher = $composer->getEventDispatcher();
$dispatcher->addListener('post-autoload-dump', [$this, 'onAutoloadDump']);
}
本地验证插件兼容性的实操步骤
别只信文档或 CI,必须在真实环境中交叉验证。
- 准备两个干净环境:一个装 Composer 1(如
composer self-update --1),一个装 Composer 2(composer self-update --2) - 在两个环境下分别执行:
composer require --dev your/plugin:dev-main,观察是否成功安装并触发activate() - 手动触发一次
composer dump-autoload,确认插件注册的post-autoload-dump事件是否被调用(加var_dump()或日志) - 如果插件提供命令(如
phpcs:install-standards),分别在 v1/v2 下运行composer list查看是否出现,再执行测试
最容易被忽略的是:插件类文件本身被 autoload,但内部引用的 v2 类在 v1 下首次加载就崩溃——这种错误不会出现在 composer install 阶段,而是在真正触发事件时才暴露。

















