runtime-api 是 Composer 用于校验插件兼容性的内部字符串常量，定义在 ComposerRuntimeApi::VERSION 中，仅在插件加载时比对版本以跳过不兼容插件，不影响 install/update 执行逻辑。
runtime-api 是什么，它不负责运行时功能
runtime-api 并不是 Composer 运行时调用的 API 接口，而是 Composer 自身在加载插件（PluginInterface）或扩展包时，用于**校验兼容性**的一个内部标识。它本质上是一个字符串常量，定义在 ComposerComposer 类中（如 RuntimeApi::VERSION），代表当前 Composer 主程序所声明的“插件可依赖的最低稳定 API 抽象层”。
这个值不会影响 composer install 或 composer update 的执行逻辑，只在插件初始化阶段被读取——如果插件声明的 require 中指定了 "composer-runtime-api": "^2.2"，而当前 Composer 版本返回的 RuntimeApi::VERSION 是 "2.1"，插件就会被跳过加载，避免因接口变更导致崩溃。
如何查当前 Composer 的 runtime-api 版本
最直接的方式是让 Composer 自己输出：
php -r "require 'vendor/autoload.php'; echo ComposerRuntimeApi::VERSION . "\n";"
但前提是项目已安装 Composer 的源码（比如通过 composer install --no-dev 后未删 vendor/composer/composer）。更通用、无需依赖项目 vendor 的方法是：
- 查看 Composer 可执行文件头部注释（适用于 phar 安装）：
head -n 20 /usr/local/bin/composer | grep -A1 'Runtime API'
- 或运行：
composer --version --no-ansi
，然后对照官方发布日志：v2.2.0+ 对应"2.2"，v2.5.0+ 对应"2.5"（注意：版本号与RuntimeApi::VERSION基本同步，但非严格一一映射，以源码为准） - 若使用 GitHub Actions 或 CI 环境，建议直接读取
COMPOSER_HOME下缓存的installed.json（不推荐，不稳定）
插件开发中误用 runtime-api 的典型错误
很多插件作者把 composer-runtime-api 当成 PHP 扩展能力开关，试图据此判断是否支持 PluginInterface::activate() 的新参数，这是错的。实际行为取决于 Composer 主程序版本，而非该字符串。
- 错误写法：
"require": { "composer-runtime-api": "^2.3" }—— 这不能保证$composer实例有getPackage()方法，只能说明插件不会被 v2.2 及以下版本加载 - 正确做法：运行时做方法存在性检测，例如
if (method_exists($composer, 'getPackage')) { ... } - 混淆
composer-plugin-api：后者才是插件生命周期接口规范（如PluginInterface定义），和runtime-api完全无关，但常被一起写进composer.json
为什么 runtime-api 不随 minor 版本自动升级
因为它的变更意味着 Composer 内部核心对象（如 Composer、RepositoryManager）的公共方法签名或行为发生不兼容改动。这类改动极少发生——过去三年仅在 v2.2（引入 getConfig() 统一入口）、v2.5（重构 EventDispatcher 初始化时机）等少数节点升级过。
所以如果你看到某个插件要求 "composer-runtime-api": "^2.4"，但它在 v2.5 下报错，大概率不是 API 版本问题，而是插件自身没适配新版本中某个被移除的私有属性访问（比如直接读 $composer->package 而非调用 getPackage()）。
真正需要警惕的，是插件文档里没提 runtime-api，却在代码里硬编码了 Composer 实例的内部结构。这种耦合比版本号本身危险得多。
