Composer插件必须实现PluginInterface接口并声明"type": "composer-plugin"，通过activate()获取$composer和$io，利用EventDispatcher监听事件，从extra读取配置，调试用$io->writeError()。
Composer 插件必须实现 ComposerPluginPluginInterface
不实现这个接口，Composer 根本不会识别你的类为插件。它要求两个方法：activate() 和 deactivate()，前者在插件加载时调用，后者极少被触发（如插件被卸载时），实际开发中通常只关注 activate()。
注意：插件类不能是匿名类，必须有明确的命名空间和可 autoload 的路径；推荐放在 src/ 下，并在 composer.json 中配置 "autoload": {"psr-4": {"MyPlugin\": "src/"}}。
-
activate()接收两个参数：$composer（ComposerComposer实例）和$io（ComposerIOIOInterface，用于输出提示或读取用户输入） - 插件必须声明类型为
"type": "composer-plugin"，否则composer install会跳过它 - 依赖
composer-plugin-api版本需与当前 Composer 主版本匹配（如 Composer 2.x 对应"composer-plugin-api": "^2.0"）
监听事件要用 EventDispatcher 注册回调
Composer 插件的核心能力来自事件系统。通过 $composer->getEventDispatcher() 获取分发器，再用 addListener() 绑定事件名与回调函数。常见事件包括：pre-install-cmd、post-autoload-dump、pre-package-install 等。
错误写法是直接在 activate() 里写业务逻辑——那只会执行一次，且无法响应命令生命周期。正确做法是把逻辑封装进回调函数，并确保回调能访问到 $io 和 $composer 上下文。
- 事件名必须拼写准确，大小写敏感；例如
post-update-cmd不是post-update-command - 回调函数接收一个
CommandEvent对象（如ComposerEventDispatcherEvent子类），从中可获取命令名、参数、运行环境等 - 若需在
autoload-dump后生成文件，记得检查$event->isDevMode()避免生产环境误操作
composer.json 的 extra 字段可透传配置给插件
用户项目可通过 composer.json 的 "extra" 区块向你的插件传参，比如：
{
"extra": {
"myplugin": {
"enabled": true,
"output-dir": "generated/"
}
}
}
在插件中用 $composer->getPackage()->getExtra() 读取，再做键存在性判断和类型校验。别直接硬编码路径或开关，否则丧失复用性。
-
getExtra()返回的是原始数组，不含默认值，所有字段都需手动 fallback - 避免在
activate()阶段就依赖用户未定义的 extra 配置，否则composer install可能因 Fatal Error 中断 - 若配置影响事件注册逻辑（如只在
"enabled": true时监听post-autoload-dump），必须在activate()内完成条件判断
调试插件最有效的方式是加 $io->writeError() + 强制重装
Composer 插件没有热加载，修改代码后必须重新执行 composer update your-plugin-name 或 composer install --no-cache 才能生效。日志只能打到 stderr，所以用 $io->writeError("debug: xxx")，而不是 echo 或 var_dump。
常见卡点：插件没被加载，往往是因为 type 不对、autoload 路径错、PHP 类名与文件名不一致，或 composer-plugin-api 版本冲突。此时看 composer diagnose 输出和 composer show -p 是否列出你的插件。
- 用
composer config --list检查是否启用了插件自动发现（默认开启，但某些自定义COMPOSER_HOME环境可能干扰） - 插件中抛出异常会中断整个 Composer 流程，调试期建议
try/catch包裹关键逻辑并用$io->writeError()输出上下文 - 不要在插件里调用
exec('composer ...')—— 容易引发递归调用或权限问题
$composer 实例里有哪些 package、lock 文件是否已写入、IO 是交互式还是静默模式」——这些必须靠实测+日志交叉验证。 
