Composer插件需同时满足三个条件才能被正确识别加载：type必须为composer-plugin，extra.class指定入口类，autoload配置确保类可自动加载；否则插件将被忽略。
Composer 插件不能通过 composer.json 的 require 直接加载运行——必须声明为 type: composer-plugin，且主类需实现 ComposerPluginPluginInterface，否则 Composer 会忽略它。
如何让 Composer 正确识别并加载你的插件
关键在 composer.json 的三个字段必须同时满足：
-
"type": "composer-plugin"—— 这是硬性前提，缺一不可 -
"extra": { "class": "MyVendor\MyPlugin\Plugin" }—— 指定入口类（命名空间+类名），路径需与autoload配置一致 -
"autoload": { "psr-4": { "MyVendor\MyPlugin\": "src/" } }—— 确保类能被 Composer 自动加载
如果插件放在项目本地（非 Packagist），还需在根项目的 composer.json 中用 repositories 指向本地路径或 VCS：
{
"repositories": [
{
"type": "path",
"url": "./my-composer-plugin"
}
],
"require": {
"my-vendor/my-composer-plugin": "*"
}
}
为什么 activate() 不执行？常见初始化陷阱
插件类必须实现 ComposerPluginPluginInterface，且 activate() 方法只在插件被首次启用时调用一次；它接收两个参数：$composer（ComposerComposer 实例）和 $io（ComposerIOIOInterface）。常见问题包括：
- 忘记
use正确的接口：必须是ComposerPluginPluginInterface，不是ComposerEventDispatcherEventSubscriberInterface - 未调用
$composer->getEventDispatcher()->addSubscriber(...)—— 单纯实现接口不会自动监听事件 - 在
activate()中直接操作$composer->getPackage()可能拿到的是锁文件解析后的CompletePackage，而非原始composer.json内容
监听 install/update 事件的正确写法
Composer 插件靠事件驱动，最常用的是 post-install-cmd 和 post-update-cmd。订阅方式必须在 activate() 中完成：
use ComposerComposer;
use ComposerIOIOInterface;
use ComposerPluginPluginInterface;
use ComposerEventDispatcherEventSubscriberInterface;
use ComposerScriptCommandEvent;
use ComposerScriptScriptEvents;
class Plugin implements PluginInterface, EventSubscriberInterface
{
public function activate(Composer $composer, IOInterface $io)
{
$dispatcher = $composer->getEventDispatcher();
$dispatcher->addSubscriber($this);
}
public static function getSubscribedEvents()
{
return [
ScriptEvents::POST_INSTALL_CMD => 'onPostInstall',
ScriptEvents::POST_UPDATE_CMD => 'onPostUpdate',
];
}
public function onPostInstall(CommandEvent $event)
{
$io = $event->getIO();
$io->write('✅ Custom plugin: post-install hook fired');
// 注意：此时 vendor/ 已写入，但 autoload_files.php 尚未生成
}
}
⚠️ 注意：post-install-cmd 在 vendor/autoload.php 生成前触发，不能依赖已安装包的类；如需调用其他包代码，应改用 post-autoload-dump 事件。
调试插件时看不到输出？绕过静默模式
Composer 默认在非交互模式下抑制插件输出。解决方法有二：
- 加
-v或--verbose参数强制显示所有$io->write()和$io->writeError() - 避免用
echo或var_dump—— 它们会被 Composer 的输出缓冲捕获或丢弃；始终走$io接口 - 临时在
activate()开头加$io->writeError('<error>[DEBUG] Plugin loaded</error>');，确保插件确实被加载
真正难调试的点在于：插件类的 autoloading 失败时 Composer 不报错，只会静默跳过；务必先用 composer dump-autoload -o 验证类能否被正常加载。
