升级 composer 之后,某个插件在 composer.json 里明明声明了 "composer-plugin-api": "^2.0",运行时却抛 class not found。这类问题不是缓存引起的,通常是版本约束与实际代码不一致。

先做隔离,再看 lock 残留
可以先用 composer remove vendor/plugin-name 临时移除,确认问题是否随之消失。若该插件承担私有源加速等关键功能,可 fork 后修改其 composer.json 的 plugin-api 约束并指向自有仓库;但也要先判断是否真的需要它——例如 prestissimo 的并行下载能力,在 Composer 2.5+ 已被原生机制取代,删掉反而更稳。
另一条线索在 composer.lock:如果之前用 2.x 生成过 lock 文件,其中可能残留 plugin-api 相关元数据,即使插件已移除,install 仍会报兼容性错误。运行 composer update --lock 可强制重写并剔除相关字段;必要时手动搜索 "plugin-api" 或插件名,删除对应 block 再试。不要直接删掉整个 lock 文件,除非你明确接受所有依赖版本浮动。
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。

约束写着兼容、代码却不兼容的三类情况
一是插件实际用了 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 手动加载插件入口来暴露真实错误点。具体接口签名可对照所用版本的源码确认。

















