插件报“not compatible”时应先运行 composer diagnose 定位不兼容插件,确认其是否声明 "composer-plugin-api": "^2.0",对已废弃插件如 hirak/prestissimo 应用 composer remove 彻底清理,避免硬加 allow-plugins 白名单。

插件报“not compatible”时先用 composer diagnose 定位问题
Composer 2.x 启动时会主动扫描所有已安装插件,composer diagnose 是唯一能快速列出不兼容插件的命令。它输出里明确标出类似 The "hirak/prestissimo" plugin is not compatible with Composer 2 的行——别跳过这步,直接删插件或降级 Composer 都是盲操作。
常见诱因不是插件本身坏了,而是它的 composer.json 里缺 "composer-plugin-api": "^2.0" 字段。去 Packagist 页面点开该插件的源码,确认 require 段是否声明了 2.x 接口支持。没声明就说明作者还没适配,不能硬等。
用 composer remove 清掉归档/废弃插件最安全
像 hirak/prestissimo、fxp/composer-asset-plugin 这类已被标记为 abandoned 的插件,官方早就不维护了。它们在 Composer 2.x 下要么加载失败,要么导致 composer install 卡死在 Loading composer repositories。
执行以下操作:
-
composer remove hirak/prestissimo(不用加--dev,它默认走全局 vendor) - 删掉
composer.lock里残留的插件条目(手动删或重跑composer update --lock) - 检查
composer.json的require-dev或plugins字段,确保没硬编码引用
移除后运行 composer install,如果不再报错且依赖正常装入,说明问题根子就在插件上。
临时保留旧插件?改 composer.json 中的 config.plugin.autoload
某些私有插件没法立刻替换,又必须让项目跑起来,可以绕过自动加载机制,只在需要时手动引入。在 composer.json 的 config 段加:
"config": {
"plugin-autoloader": false
}
然后在代码里显式 require 插件入口文件(比如 vendor/your-org/legacy-plugin/src/Plugin.php),并手动调用其 activate() 方法。这不是长期方案,但能帮你抢出时间做迁移。
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
注意:plugin-autoloader: false 不影响其他正常插件,只对未声明 composer-plugin-api 兼容性的插件生效;同时要确保 PHP include_path 或自动加载规则能覆盖到该文件路径。
别碰 allow-plugins 字段除非你清楚后果
Composer 2.2+ 引入了 allow-plugins 白名单机制,默认禁止所有插件执行。很多人看到报错第一反应是把插件名加进这个字段,比如:
"allow-plugins": {
"hirak/prestissimo": true
}
这只会让报错从 “not compatible” 变成 “Class Prestissimo\Plugin not found”,因为插件本身代码根本没适配 2.x 的生命周期钩子。真正该加白名单的,是那些已更新至 composer-plugin-api ^2.0 且通过 composer require 正常安装的插件。
如果你加了白名单却仍报错,八成是插件没重装——先 composer remove,再 composer require 它的最新版(不是原版本),否则白名单只是给一个不存在的类开了门。
插件回滚本质不是版本倒退,而是确认它是否还在被维护、能否接入新接口。强行保留一个连 composer-plugin-api 都不声明的插件,等于在依赖树里埋定时炸弹——下次 CI 构建或 PHP 升级,它可能突然炸开,而且毫无征兆。










