post-package-install钩子仅在composer install/update整体结束时触发一次，无法捕获单个包安装事件；应使用Composer插件监听InstallerEvents::POST_PACKAGE_INSTALL事件获取PackageInterface实例，或改用scripts+post-autoload-dump等更稳定方案。
post-package-install 钩子根本不会触发单个包的安装完成事件
Composer 的 post-package-install 不是为“某个包装完就执行一次”设计的——它只在 composer install 或 composer update 整体流程结束时触发一次，且不带具体包信息。你写个脚本监听这个钩子，指望它对 monolog/monolog 单独执行某操作，注定失败。
常见错误现象：
• 在 composer.json 里配了 "post-package-install" 脚本，但安装新包后脚本没运行
• 脚本运行了，但 $event->getOperation() 返回 null 或类型不可靠
• 误以为能拿到刚装的包名、版本、源路径，实际只能拿到模糊的 InstallOperation 实例，且仅在 update 过程中部分场景可用
- 该钩子实际触发时机：整个依赖图解析+下载+解压+安装全部完成后，才调用一次
- 它不区分“是哪个包导致这次安装”，也不保证每次
composer require foo/bar都触发（比如缓存命中时可能跳过） - 官方文档已明确标注：此事件“experimental”，不建议依赖，未来可能移除
想对特定包做安装后处理？用 plugin + InstallerEvent 更可靠
真正能捕获“某个包刚刚被装进 vendor”的时机，是通过 Composer Plugin，在 InstallerEvent 中监听 post-package-install 对应的底层事件。这不是配置项，是写 PHP 类。
使用场景：给 laravel/framework 安装后自动生成配置文件；为 drush/drush 注册 bin 脚本；对私有包解密资源文件。
- 必须实现
Composer\Plugin\PluginInterface和Composer\EventDispatcher\EventSubscriberInterface - 订阅
Composer\Installer\InstallerEvents::POST_PACKAGE_INSTALL（注意不是字符串"post-package-install"） -
$event->getOperation()->getPackage()才能稳定拿到刚安装的PackageInterface实例 - 插件需声明为
type: composer-plugin，并 require 到根项目或全局 composer
示例关键片段：
public static function getSubscribedEvents()
{
return [
InstallerEvents::POST_PACKAGE_INSTALL => 'onPostPackageInstall',
];
}
public function onPostPackageInstall(InstallerEvent $event)
{
$package = $event->getOperation()->getPackage();
if ($package->getName() === 'acme/private-tool') {
// 执行解密、复制模板等操作
}
}
别硬扛钩子：多数需求其实该用 scripts + require-dev + 自定义命令
如果你只是想“装完 laravel-mix 后跑一次 npm install”，或者“加了个测试工具后生成 stub 文件”，根本不需要碰事件钩子或插件——这些属于开发流动作，不是 Composer 安装流程的一部分。
性能 / 兼容性影响：
• 插件要 autoload、要兼容 Composer 2.x/3.x 版本差异，维护成本高
• post-package-install 配置在不同 Composer 版本行为不一致，CI 环境容易出错
• 大多数团队成员根本不知道钩子在哪生效，调试困难
- 把操作包装成
composer run build-assets，写进scripts，手动触发更可控 - 用
require-dev声明工具依赖，再配合post-autoload-dump（它稳定、带 autoloader 实例）做轻量初始化 - 对私有包，直接在包自身
composer.json里写post-install-cmd，由包作者控制，使用者无感
最容易被忽略的坑：vendor 目录权限、符号链接与并发安装
即使你成功监听到某个包安装完成，下一步操作也极可能失败——因为 Composer 默认不保证 vendor/acme/foo 此刻已可读写，尤其在 Docker、Windows WSL 或 CI 并行任务中。
-
post-package-install触发时，vendor 下该包目录可能还是临时解压路径（如vendor/composer/xxxxxx），尚未 mv 到最终位置 - 如果包含
bin文件，Composer 会稍后才创建软链，此时去 chmod 会报错 - 多个包同时安装时，事件可能交叉触发，没有顺序保证；不要假设 A 包一定在 B 包之前装完
真要改文件，优先用 post-autoload-dump，它发生在所有包就位、autoloader 生成完毕之后，路径确定、权限稳定、时机可信。
