Composer插件兼容问题不能靠重装解决，因其v1/v2间类路径、方法签名及能力注册机制彻底断裂；删vendor、清lock或重装Composer均无效，运行时类加载失败是硬性阻断。
为什么 composer plugin 兼容问题不能靠“重装”解决
因为 Composer 插件的激活逻辑和事件系统在 v1 和 v2 之间是断裂的——不是版本号差异，而是类路径、方法签名、能力注册机制全变了。你删了 vendor/、清了 composer.lock、甚至重装 Composer 本身，只要插件代码里写了 Composer\Plugin\Capability\CommandProvider，它在 Composer 1 环境下就会直接 Fatal error: Class 'Composer\Plugin\Capability\CommandProvider' not found。这不是缓存或锁文件的问题，是运行时类加载层面的硬性失败。
用 git bisect 定位插件兼容性退化点
当插件在某次更新后突然在 Composer 1 环境中失效（但 Composer 2 下正常），说明变更引入了 v2-only 的 API 调用。这时该用 git bisect 快速收口，而不是逐行扫 diff。
- 先确认一个已知能跑通的旧 commit（比如上个 tagged 版本）：
git bisect good v1.2.0 - 再标记当前坏状态：
git bisect bad HEAD - 每次 bisect 停驻后，手动执行：
composer install --no-plugins（跳过插件激活）→ 然后用最小环境测试插件类是否可实例化：php -r "var_dump(class_exists('MyPlugin'));" - 若报错，
git bisect bad；若通过，git bisect good
重点盯住新增的 use 语句、new 实例化、以及 activate() 方法体内的调用——这些是最常埋雷的位置。
class_exists() 不是万能胶，得配 method_exists() 一起用
只判断类存在还不够。比如 Composer\Script\Event 在 v1 和 v2 中都存在，但 v2 里它的构造函数参数变了，直接 new 会炸。所以必须组合检测：
-
class_exists('Composer\Plugin\Capability\CommandProvider')→ 判断是否走 v2 capability 路径 -
method_exists($composer, 'getPluginManager')→ 防止 v1 下调用不存在的方法 -
method_exists($event, 'getIO')→ v1 的Event没这个方法，v2 才有
所有对 Composer\Package\*、Composer\Repository\* 等内部类的访问，都要前置 class_exists()，否则 v1 下 autoload 失败就终止了，根本进不到你的降级逻辑里。
composer.json 里的 "composer-plugin-api" 字段只能填一个值
别被语义化版本迷惑。写 "composer-plugin-api": "^1.0 || ^2.0" 看似合理，实际会让 Composer 2 直接拒绝安装插件（v2 不认 v1 的 API 声明），而 Composer 1 又无法解析 v2 的 capability 注册语法。官方校验器会硬拦截。
- 想支持老项目（PHP 7.2 + Composer 1）→ 锁死
"composer-plugin-api": "^1.1.0" - 想用 v2 新特性（如
activate(Composer $composer, IOInterface $io)）→ 升到"composer-plugin-api": "^2.2.0" - 所谓“兼容”，只发生在你自己的 PHP 代码里，不在
composer.json声明里
最易被忽略的是：__construct() 或静态初始化块里不能 new 任何 v2-only 类——哪怕外面包了 if (class_exists(...))，PHP 解析阶段就会 fatal。降级逻辑必须全部收束在 activate() 或后续可延迟调用的方法里。
