Composer插件的composer-plugin-api版本声明必须唯一明确,不可写"^1.0 || ^2.0",否则Composer会因API断裂直接拒绝安装;type必须为"composer-plugin",extra.class须指向可自动加载的完整类名,且运行时检测逻辑只能在activate()内执行。

composer-plugin-api 版本声明必须唯一且明确
Composer 插件的 composer-plugin-api 不能写成 "^1.0 || ^2.0",否则 Composer 自身会拒绝安装:v2 直接报错“Plugin X is not compatible with Composer 2”,v1 则因无法解析 v2 的 capability 声明而失败。这不是语义化版本能兜住的问题,而是 API 层级断裂。
你必须在 composer.json 的 require 字段中只写一个确定版本:
-
"composer-plugin-api": "^1.1.0"→ 仅支持 Composer 1(PHP -
"composer-plugin-api": "^2.2.0"→ 仅支持 Composer 2(推荐,含activate(Composer $composer, IOInterface $io)签名等)
别指望 Composer 自动选路——它不干这事。
type 字段是插件加载的硬性开关
没有 "type": "composer-plugin",Composer 根本不会把它当插件看,也不会扫描、不会 autoload、不会调用 activate()。漏掉这个字段,等于没写插件。
常见错误包括:
- 写成
"type": "library"或留空 - 拼错为
"composer_plugin"(下划线非法)或"composerplugin"(缺短横线) - 放在子包的
composer.json里,但主项目没require它
这个字段必须和 require、autoload 同级,位于根 composer.json 顶层。
使用 extruct 从原始 HTML 中提取机器可读的元数据,以便代理可以在不依赖脆弱的全页解析的情况下对页面进行分类、去重或丰富。它最适合元数据采集工作流,而不适用于爬取整个网站或渲染 JavaScript 密集型页面。
extra.class 必须指向可 autoload 的完整类名
extra.class 是 Composer 查找插件入口的唯一路径,它不是文件路径,而是带命名空间的类名,例如 "MyVendorMyPluginPlugin"。如果类不存在、命名空间与 autoload 配置不匹配,或类没实现 ComposerPluginPluginInterface,插件就静默失效——无报错、无日志、无提示。
检查点:
-
autoload中的 PSR-4 映射是否覆盖该命名空间,如"MyVendor\MyPlugin\": "src/" - 类文件是否真在
src/Plugin.php,且含class Plugin implements ComposerPluginPluginInterface - 是否用了
use ComposerPluginPluginInterface,而不是拼错成EventSubscriberInterface等其他接口
allow-plugins 不影响插件声明,只控制运行时授权
allow-plugins 是消费者项目的配置项,和插件自身的 composer.json 无关。你在插件里写 "allow-plugins": true 没用,它只在使用该插件的项目中生效。
若你的插件叫 my-vendor/my-plugin,使用者必须在其项目 composer.json 的 config.allow-plugins 中显式放行:
"config": {
"allow-plugins": {
"my-vendor/my-plugin": true
}
}
否则即使插件声明完全正确,也会被 Composer 拦在运行前——这是安全机制,不是兼容性问题。
插件兼容性最易被忽略的点,其实是运行时环境探测逻辑的位置:所有 class_exists('ComposerPluginCapabilityCommandProvider') 这类判断,必须放在 activate() 方法体内,绝不能塞进 __construct() 或静态块里;否则 Composer 1 下直接 fatal error。










