Composer插件必须声明"type": "composer-plugin"且实现PluginInterface，激活方法需严格匹配签名并注册事件监听器；输出须通过IOInterface，调试应优先使用composer diagnose和-v参数。
Composer插件必须实现 PluginInterface 才能被识别
Composer 不会自动加载任意包为插件，必须在插件的 composer.json 中声明 "type": "composer-plugin"，且主类实现 Composer\Plugin\PluginInterface。否则即使安装成功，composer install 时也完全不会调用你的代码。
常见错误是只写了类、没设 type，或忘了在 activate() 方法里注册事件监听器。激活方法签名必须是 activate(Composer\Composer $composer, Composer\IO\IOInterface $io)，参数类型错一个就会静默失败。
- 插件类需放在
autoload["psr-4"]下，并确保命名空间与文件路径严格匹配 -
deactivate()和uninstall()通常留空即可，除非你要清理临时文件或钩子 - 不要在
activate()里做耗时操作（如远程请求），它会在每次 composer 命令启动时执行
监听 post-install-cmd 和 post-update-cmd 的正确写法
这两个事件最常用，但容易混淆触发时机：post-install-cmd 只在首次 composer install（无 composer.lock 时）触发；而 post-update-cmd 在 composer update 或带 --with-dependencies 的 install 时触发。多数场景应同时监听二者。
注册方式是调用 $composer->getEventDispatcher()->addListener()，事件名是字符串，回调是闭包或可调用数组。注意闭包必须引用 $io 和 $composer，否则拿不到上下文：
use Composer\Script\Event;
use Composer\Installer\PackageEvents;
$dispatcher = $composer->getEventDispatcher();
$dispatcher->addListener('post-install-cmd', function (Event $event) use ($io, $composer) {
$io->write('✅ Installed packages: ' . count($composer->getPackage()->getRequires()));
});
$dispatcher->addListener('post-update-cmd', function (Event $event) use ($io, $composer) {
$io->write('? Updated lock file');
});
- 别用
ScriptEvents::POST_INSTALL_CMD这类常量——它们属于脚本事件，插件事件名是纯字符串 -
回调函数参数类型必须是
Composer\EventDispatcher\Event或其子类（如CommandEvent），不能写ScriptEvent - 如果需要访问已安装包列表，要用
$composer->getRepositoryManager()->getLocalRepository()->getPackages()，不是$composer->getPackage()
通过 Composer\IO\IOInterface 安全输出与交互
插件里不能直接 echo 或 var_dump，所有输出必须走 $io->write() 或 $io->ask()。否则在 CI 环境或非 tty 场景下会报错，甚至阻塞流程。
$io 还提供 isInteractive() 和 isVerbose()，用于判断当前是否允许提问或是否开启详细日志。比如要提示用户确认危险操作，得先检查交互状态：
if ($io->isInteractive()) {
$confirmed = $io->askConfirmation('⚠️ This will delete vendor/xxx. Continue? [y/N] ', false);
if (!$confirmed) {
$io->writeError('Aborted.');
return;
}
}
-
$io->writeError()输出到 stderr，适合错误和警告，会被 CI 工具捕获为失败信号 - 避免在非交互模式下调用
$io->ask()，会卡住进程；务必用isInteractive()包裹 - 颜色支持用
调试插件时优先检查 composer diagnose 和日志级别
插件不生效？先运行 composer diagnose，它会检查插件是否被正确识别、是否有 autoload 冲突、是否 PHP 版本不兼容。比手动翻日志快得多。
真正的问题往往藏在静默中：Composer 默认不输出插件加载细节。加 -v 或 --verbose 才能看到 “Loading plugin MyVendor\MyPlugin\Plugin” 这类行。更深层问题（如事件未触发）需结合 COMPOSER_MEMORY_LIMIT=-1 COMPOSER_DISABLE_XDEBUG=1 composer update -v 排除内存和扩展干扰。
- 插件类抛出异常时，Composer 会截断堆栈，只显示 “Plugin exception” —— 开发期建议在
activate()里加try/catch并用$io->writeError()打印完整消息 - 修改插件后，Composer 缓存可能复用旧字节码，执行
composer clear-cache再试 - 本地开发建议用
path仓库方式加载插件，避免反复composer require，改完代码直接生效
事件监听本身不难，难的是 Composer 的生命周期短、上下文隔离强、错误反馈弱。每加一个监听器，都要验证它在 install/update/dump-autoload 等不同命令下的行为是否符合预期——尤其当多个插件共存时，监听顺序和副作用很难推演。
