Composer 不提供运行时插件系统，仅支持在 install/update 等生命周期中干预依赖安装的 composer-plugin 类型包，需声明 type 为 "composer-plugin" 并实现 PluginInterface。
Composer 本身不提供运行时“插件系统”供你在项目中动态加载或启用第三方功能模块——它只有 composer-plugin 类型的包，用于在 composer install、update 等生命周期中干预依赖安装行为。你不能像 Laravel 的 Service Provider 那样在应用运行时通过 Composer 插件注册路由或中间件。
什么是 composer-plugin？
它是一种特殊类型的 Composer 包，必须声明 "type": "composer-plugin"，并实现 ComposerPluginPluginInterface。这类插件只在 Composer 命令执行期间被加载（如 composer install），用于修改仓库行为、注入脚本、重写 autoload、拦截包安装等底层操作。
- 典型用途：自动发布构建产物、校验包签名、替换 dist URL、生成 stub 文件
- 不能用于业务逻辑扩展：比如“给 Eloquent 加个新方法”或“为 Symfony Console 注册新命令”
- 必须在
composer.json的require中声明，并且其autoload必须能被 Composer 自身加载（通常用psr-4）
如何开发一个最小可用的 composer-plugin
创建一个独立目录（如 my-composer-plugin），结构如下：
{
"name": "acme/my-composer-plugin",
"type": "composer-plugin",
"autoload": {
"psr-4": {
"Acme\ComposerPlugin\": "src/"
}
},
"require": {
"composer-plugin-api": "^2.0"
},
"extra": {
"class": "Acme\ComposerPlugin\MyPlugin"
}
}
extra.class 是关键字段，指明入口类；该类必须实现 ComposerPluginPluginInterface。例如：
namespace AcmeComposerPlugin;
use ComposerComposer;
use ComposerIOIOInterface;
use ComposerPluginPluginInterface;
class MyPlugin implements PluginInterface
{
public function activate(Composer $composer, IOInterface $io)
{
$io->write('<info>[MyPlugin] activated</info>');
}
}
然后在目标项目中执行：composer require acme/my-composer-plugin:dev-main --dev，下次运行 composer install 就会触发 activate()。
为什么你的插件没生效？常见坑点
插件不工作往往不是代码问题，而是配置或环境限制：
-
extra.class指向的类未被正确 autoload —— 检查autoload路径是否匹配实际文件位置 - 插件类型未声明为
"type": "composer-plugin"—— 缺少该字段会导致 Composer 完全忽略它 - PHP 版本或 Composer 版本不兼容 ——
composer-plugin-api有严格版本对应关系（^2.0对应 Composer 2.x） - 插件被禁用：全局配置中设置了
disable-plugins: true，或运行时加了--no-plugins - 插件抛出异常但被静默吞掉 —— 在
activate()或deactivate()中加throw new Exception('debug')测试是否进入
替代方案：如果你真想在项目里“装插件”
别走 Composer 插件这条路。更合理的方式是：
- 用 PSR-15 / PSR-16 等标准定义接口，让业务包实现它们，主项目通过
composer require引入后手动注册（如 Laravel 的ServiceProvider） - 借助框架能力：Symfony Bundle、Laravel Package、WordPress 插件机制，它们才是面向运行时的功能扩展体系
- 用 Composer 的
scripts+ 自定义命令封装常用操作（如php vendor/bin/mytool init），比写插件简单得多
真正需要 Composer 插件的场景极少，多数人混淆了“依赖管理阶段的钩子”和“应用运行时的扩展”。一旦开始往插件里塞业务逻辑，就说明设计方向错了。
