必须包含name、type、autoload和require字段:name须为vendor/name格式,type决定包角色(如composer-plugin),autoload需配置psr-4,require须声明composer-plugin-api版本。

composer.json 必须包含哪些字段才能被正常识别
Composer 不会加载缺少 name 和 type 的包,哪怕只是本地开发。没有 name(格式必须是 vendor/name,比如 myorg/my-package),Packagist 或私有仓库根本无法索引;没有 type,Composer 就不知道这是库、命令行工具还是插件——尤其写扩展包时,type 决定是否被 composer-plugin-api 识别。
最小可用的 composer.json 至少要包含:
-
name:必须为小写字母、数字、短横线、下划线,且含一个/ -
type:扩展包通常设为composer-plugin -
autoload:至少声明 PSR-4 自动加载,否则类找不到 -
require中明确依赖composer-plugin-api版本(如^2.0或^1.0)
type=composer-plugin 时 autoload 和 extra 的关键配置
不是所有 type=composer-plugin 包都能被自动激活。Composer 要求插件类必须可自动加载,且在 extra 中声明入口类名——否则即使安装成功,也完全不执行。
常见错误是只写了 autoload,却漏掉 extra 块:
{
"name": "myorg/my-composer-plugin",
"type": "composer-plugin",
"autoload": {
"psr-4": {
"MyOrg\ComposerPlugin\": "src/"
}
},
"require": {
"composer-plugin-api": "^2.0"
},
"extra": {
"class": "MyOrg\ComposerPlugin\MyPlugin"
}
}
注意:extra.class 的值必须是完整命名空间+类名,且该类需实现 ComposerPluginPluginInterface;如果用的是 Composer 2.x,还要确保继承 ComposerPluginCapabilityCommandProvider(如需提供自定义命令)。
将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。
如何避免版本冲突和 API 不兼容
Composer 插件的 composer-plugin-api 版本不是可选的——它和当前 Composer 主程序强绑定。用错版本会导致插件静默失效或直接报错 PluginManager::createPlugin(): Plugin ... is not compatible with this version of Composer。
- Composer 1.x 对应
composer-plugin-api: ^1.0 - Composer 2.0–2.2 对应
composer-plugin-api: ^2.0 - Composer 2.3+ 开始支持
^2.3,但向后兼容^2.0
如果你的插件需要同时支持 Composer 1 和 2,不能靠单个 composer.json 实现,得用 conflict 分开发布,或者干脆放弃 v1 支持——现在绝大多数 CI 和用户环境已是 Composer 2.2+。
测试插件是否真正生效的实操方法
光看 composer install 没报错不等于插件在运行。最可靠的验证方式是加日志或抛异常,然后在真实项目里触发:
- 在插件
activate()方法开头插入file_put_contents('/tmp/plugin-activated', 'yes'); - 在目标项目中执行
composer dump-autoload -o(强制重载插件) - 检查
/tmp/plugin-activated是否生成;没生成说明extra.class错了、类路径不对,或autoload没覆盖到 - 若插件提供了命令,运行
composer list | grep your-command看是否出现
别依赖 composer show 显示插件列表——它只查已安装包,不验证是否激活成功。










