Composer 1 和 2 插件 API 完全不兼容，无法通过版本范围声明实现“一次编写、两端运行”，必须用 class_exists() 等运行时检测分路径兼容，且 composer.json 中必须明确指定单一 plugin-api 版本。
Composer 1 和 2 的插件 API 根本不兼容
不能靠 "composer-plugin-api": "^1.0 || ^2.0" 声明实现“一次编写、两端运行”。Composer 自身在加载阶段就会校验该字段：v2 看到 ^1.0 直接拒绝安装，v1 遇到 v2 新增的 capability 类（如 Composer\Plugin\Capability\CommandProvider）会报 Class not found。这不是语义化版本能弥合的断层，而是事件系统、类路径、激活时机、方法签名的全面重构。
运行时探测才是唯一可行的兼容路径
所有跨版本逻辑必须包裹在 class_exists() 或 method_exists() 判断中，且只能在 activate() 入口或后续调用链中执行——绝不能在构造函数或静态初始化块里直接 new v2 特有类。
- 检测旧事件存在：
class_exists('Composer\Script\Event')→ 走 v1 事件监听（pre-install-cmd等） - 检测新 capability 类：
class_exists('Composer\Plugin\Capability\CommandProvider')→ 注册命令提供器 - 包对象方法要降级：
$package->getNamesWithStability()（v2）不能直接调$package->getNames()（v1），得先method_exists($package, 'getNamesWithStability') - 对
Composer\Package\Link等内部类的任何引用，都必须前置class_exists()，否则 v1 下 fatal error
composer.json 里只能声明一个确定的 plugin-api 版本
你必须二选一："composer-plugin-api": "^1.1.0"（保 PHP 7.2 + Composer 1 项目），或 "composer-plugin-api": "^2.2.0"（启用 v2 的 activate(Composer $composer, IOInterface $io) 签名和 capability 机制）。声明双版本范围会导致 Composer 安装失败，不是警告，是硬拦截。
所谓“兼容”，实际是你代码里主动分路径；Composer 不负责桥接，只负责按声明版本决定是否加载你的插件类。
merge-plugin 这类工具插件要严格按 Composer 大版本选型
wikimedia/composer-merge-plugin 的 1.4.x 只支持 Composer 1，2.0.x 起才适配 Composer 2。混用会直接导致 Class 'Composer\Plugin\Capability\...' not found 或 Plugin is not compatible with Composer 2 错误。
- 确认当前 Composer 版本：
composer --version - Composer 1.x →
composer require wikimedia/composer-merge-plugin:^1.4 - Composer 2.x →
composer require wikimedia/composer-merge-plugin:^2.0 - 升级前先
composer remove wikimedia/composer-merge-plugin，再重装对应大版本
边界划在哪？不在文档里，而在 class_exists() 的 if 分支里，在 composer.json 中那个不可妥协的 composer-plugin-api 字段值里——越试图模糊这个边界，越容易在 CI 上栽跟头。
