Composer插件必须实现Composer\Plugin\PluginInterface接口并声明"type": "composer-plugin"，且activate()和deactivate()方法不可省略；路径操作须通过$composer->getConfig()->get()获取，读取composer.json应使用$composer->getPackage()；事件监听需在activate()中注册，签名需严格匹配；发布前须限定composer-plugin-api版本并实测兼容性。
Composer插件必须实现 Composer\Plugin\PluginInterface
Composer 插件不是随便写个类就能被识别的，核心约束是必须实现 Composer\Plugin\PluginInterface 接口，并在 composer.json 中声明 "type": "composer-plugin"。否则 Composer 启动时根本不会加载它。
常见错误是只写了类但没实现接口，或者实现了接口却漏了 activate() 和 deactivate() 方法——这两个方法是强制要求的，哪怕空实现也得有。
-
activate()里通常注册事件监听器（如EventDispatcher的post-install-cmd） -
deactivate()一般留空，除非你要清理全局状态 - 插件类构造函数不能依赖未初始化的 Composer 实例；
$composer和$io是activate()的参数，不是构造时传入的
如何在插件中安全访问项目根目录和 composer.json
插件运行时不一定在项目根目录下执行，getcwd() 不可靠。正确方式是通过 $composer->getConfig()->get('vendor-dir') 反推，或更稳妥地用 $composer->getPackage()->getAutoload() 等已解析好的元数据。
想读取当前项目的 composer.json 内容？别直接 file_get_contents('composer.json')——路径可能错，且没经过 Composer 的 schema 校验和 normalize 处理。应该用：
$package = $composer->getPackage(); $extra = $package->getExtra(); // 安全读取 extra 字段
- 所有路径操作请优先使用
$composer->getConfig()->get('xxx-dir')获取配置值 - 修改
composer.json必须调用$composer->getIO()->writeError()提示用户手动运行composer update，插件不能自动重写文件 - 不要在插件里调用
Composer\Script\Event相关逻辑，那是脚本（scripts）的职责，插件应专注扩展生命周期行为
调试插件时为什么 post-autoload-dump 事件不触发
这个事件只在生成自动加载文件时触发（比如 composer install 或 composer dump-autoload），但默认情况下，如果 vendor/autoload.php 已存在且无变更，Composer 会跳过该事件。开发阶段建议加 --no-cache 和 -v 参数强制刷新并查看完整日志。
- 注册事件监听必须在
activate()中完成，且用$eventDispatcher->addListener('post-autoload-dump', [$this, 'onPostAutoloadDump']) - 监听器方法签名必须是
public function onPostAutoloadDump(Event $event)，类型提示不能省略，否则反射失败静默忽略 - 插件代码变更后需运行
composer update --no-scripts重新安装插件本身，否则旧版本仍在vendor/中缓存
发布插件前必须验证 composer-plugin-api 兼容性
Composer 主版本升级常破坏插件 ABI，比如 v2.0 移除了 Composer\Package\PackageInterface::getNames()，改用 getNamesWithStability()。插件的 composer.json 必须明确限定 "require": { "composer-plugin-api": "^2.0" } 或对应版本，否则用户安装时可能遇到 PluginManager::createPlugin() failed 错误。
实际兼容性测试不能只看本地环境：用 composer create-project composer/composer:2.5.8 /tmp/test-composer 拉一个指定版本的 Composer 二进制，再在干净项目中 require 你的插件测试。
- 不要在插件中硬编码
vendor/bin/composer路径，用$_SERVER['argv'][0]判断当前执行的是哪个 Composer 实例 - 避免使用
Composer\Util\Filesystem等内部工具类，它们没有稳定 API，v2.6 可能重构或移除 - 最隐蔽的坑：插件的
autoload配置若含psr-4映射，必须确保命名空间与实际目录结构严格一致，否则 Composer 加载失败不报错，只静默跳过插件
