composer diagnose 会直接指出不兼容插件名称及原因,如“Plugin hirak/prestissimo is not compatible with Composer 2.x”,并聚焦问题于插件自身声明,不自动修复但可快速定位。

composer diagnose 会直接告诉你哪个插件不兼容
这是最省力的起点。运行 composer diagnose 后,如果输出里出现类似 Plugin hirak/prestissimo is not compatible with Composer 2.x 的提示,就不用再猜了——它已经把问题插件名、不兼容原因和位置都列出来了。
注意:这个命令不会自动修复,但它能过滤掉环境、网络、权限等干扰项,把问题聚焦在插件声明本身。
- 检查该插件的
composer.json,重点看require段是否包含"composer-plugin-api": "^2.0" - 如果插件已归档(如
hirak/prestissimo),composer diagnose仍会报错,但错误本质是类找不到(Class Prestissimo\Plugin not found),不是语法或解析失败 - 有些插件作者悄悄发布了兼容版但没更新 README,可先试
composer update vendor/plugin-name,比删插件更轻量
插件作者没适配时,别急着降级 Composer
看到 Plugin X is not compatible 就回退到 Composer 1.x 是常见误区。Composer 1.x 已停止维护,且存在已知安全漏洞,2026 年继续用它等于主动暴露攻击面。
真正可持续的做法是替换或绕过问题插件:
- 用
composer remove vendor/plugin-name临时移除(例如composer remove hirak/prestissimo) - 若该插件功能关键(如私有源加速),可 fork 后修改其
composer.json中的composer-plugin-api版本,并指向你自己的 Git 仓库或私有 Packagist - 确认项目是否真需要它:很多插件(如
prestissimo)在 Composer 2.5+ 中已被原生并行下载机制取代,删掉反而更稳
lock 文件残留 2.x 字段也会触发兼容性误报
升级 Composer 后,如果之前用 2.x 生成过 composer.lock,而某些插件未适配,lock 文件里可能存有 plugin-api 相关元数据。此时即使插件已移除,composer install 仍可能报错。
这不是缓存问题,而是 lock 文件本身带了旧平台语义:
- 运行
composer update --lock可强制重写 lock 文件,剔除插件相关字段 - 若仍报错,可手动打开
composer.lock,搜索"plugin-api"或插件名,删掉对应 block 后再试 - 注意:不要直接删整个 lock 文件——除非你明确接受所有依赖版本浮动
为什么有些插件“看起来兼容”却仍报错
比如插件的 composer.json 声明了 "composer-plugin-api": "^2.0",但运行时还是抛 Class not found。这通常是因为:
- 插件实际代码里用了 Composer 2.x 新增的接口(如
PluginInterface::activate()参数签名变化),但 composer.json 没同步更新约束 - 插件依赖了另一个不兼容的子插件,而
composer diagnose只报顶层名称 - PHP 版本不匹配:Composer 2.9.6 要求 PHP ≥ 8.0,若插件内部用了
#[Attribute]等语法,PHP 7.4 下必然 fatal error
这种情况下,composer diagnose 不会预警,得靠 php -d display_errors=1 -d error_reporting=-1 vendor/autoload.php 手动加载插件入口文件来暴露真实错误点。


















