Composer插件通过事件钩子响应生命周期动作，需明确事件时机（如pre-autoload-dump、post-package-install）；调试应使用$io->writeError()输出、path仓库实现热加载，并检查allow-plugins白名单。

Composer插件的执行时机与事件监听点

Composer 插件不是按顺序“运行”的脚本，而是通过事件钩子（event hooks）响应生命周期动作。调试的第一步是确认你想观察的阶段：是 pre-install-cmd、post-autoload-dump，还是 post-package-install？不同事件触发条件差异很大——比如 pre-autoload-dump 只在 composer install 或 composer dump-autoload 时触发，而 post-root-package-install 仅在项目根包安装完成时触发一次。

最直接的验证方式是在插件的 activate() 方法里加日志，并确保该插件已启用：

public function activate(Composer $composer, IOInterface $io)
{
    $io->writeError('[DEBUG] Plugin activated');
    $composer->getEventDispatcher()->addListener('pre-autoload-dump', [$this, 'onPreAutoloadDump']);
}

注意：$io->writeError() 是唯一能稳定输出到控制台的方式，echo 或 var_dump() 在某些 Composer 版本中会被静默丢弃。

如何让插件在本地开发中实时生效？

Composer 默认从 vendor 加载插件，改代码后要反复 composer update 太慢。正确做法是用 path 仓库 + minimum-stability: dev 让 Composer 直接软链接本地目录：

• 在项目根 composer.json 中添加：

"repositories": [
  {
    "type": "path",
    "url": "../my-composer-plugin"
  }
],
"require": {
  "vendor/my-composer-plugin": "*"
},
"minimum-stability": "dev"

• ../my-composer-plugin 必须包含有效的 composer.json，且 "type": "composer-plugin"
• 执行 composer require vendor/my-composer-plugin:dev-main --no-update 再 composer update vendor/my-composer-plugin，即可建立 symlink
• 修改插件 PHP 文件后无需重装，下次命令运行即生效

常见调试失败原因：事件未注册或被跳过

即使写了 addListener()，事件也可能没触发——这不是代码问题，而是 Composer 的执行路径决定的：

• composer install --no-autoloader 会跳过所有 autoload 相关事件（如 pre-autoload-dump）
• composer update --lock 不安装包，因此 post-package-install 类事件不会触发
• 插件类未正确声明 implements PluginInterface，或 composer.json 缺少 "extra": {"class": "MyPlugin"}
• 多个插件监听同一事件时，执行顺序由 Composer 内部排序决定，无法保证；若需强依赖，应改用 PluginInterface::activate() 中主动调用逻辑

快速验证事件是否注册成功：运行 composer show -p 查看已加载插件列表；再加一句 $io->writeError('[DEBUG] Listener registered for pre-autoload-dump'); 在 activate() 末尾，确认插件至少被加载了。

调试时不要忽略 Composer 的静默模式与错误捕获

Composer 在非交互模式下会抑制大部分输出，尤其当 IOInterface 被封装过（如某些 CI 环境）。真正可靠的调试手段只有两种：

• 写文件日志（注意权限和路径）：

  file_put_contents('/tmp/composer-plugin-debug.log', date('c') . " onPreAutoloadDump\n", FILE_APPEND);

• 抛出异常强制中断并打印堆栈：

  throw new \RuntimeException('[DEBUG] Reached post-autoload-dump');

  （仅限开发环境）

另外，composer diagnose 不能检测插件逻辑错误，它只检查 JSON 格式和网络连通性。真要定位执行卡点，得靠 composer install -v（verbose）配合插件内 $io->writeError() 输出交叉比对。

最易被忽略的一点：Composer 2.2+ 默认启用插件白名单机制（config.allow-plugins），如果项目 composer.json 里没显式允许你的插件，它根本不会被加载——连 activate() 都不会执行。