需将脚本写在 composer.json 的 scripts 字段下，键名为合法事件名或自定义名；值支持字符串、字符串数组或关联数组，推荐数组形式避免转义问题；仅 scripts 下内容被识别，extra 或拼错字段（如 script）均无效。
composer.json 里的 scripts 怎么写才生效？
必须把命令写在 composer.json 的 scripts 字段下，且键名是合法的事件名或自定义脚本名。Composer 不会自动执行任意字段，只认 scripts 下的内容。
常见错误：把脚本写在 extra 或根级，或者拼错字段名（比如写成 script 少了个 s）。
- 脚本值可以是字符串（单条命令）、字符串数组（顺序执行）、或关联数组（含
cmd和dev等选项） - 推荐用数组形式，避免 shell 特殊字符转义问题，例如：
["php -v", "php artisan optimize:clear"]
- 如果脚本需区分环境，可用
"@composer run-script --no-dev xxx"手动控制，但更稳妥的是在脚本内部判断$_ENV['COMPOSER_DEV_MODE']
哪些钩子事件能被自动触发？
不是所有事件都默认激活——只有 Composer 在执行特定命令（如 install、update、require）时，才会按顺序触发对应生命周期钩子。
关键钩子包括：pre-install-cmd、post-install-cmd、pre-update-cmd、post-update-cmd、pre-autoload-dump、post-autoload-dump。其中 post-autoload-dump 是最常用于生成代理类或刷新缓存的时机。
-
post-autoload-dump在vendor/autoload.php重生成后立即触发，适合运行phpstan analyse或清理 opcache -
pre-autoload-dump在 autoloader 重建前触发，适合检查类文件是否缺失或格式是否合规 -
post-root-package-install只在 root 包（即你当前项目）安装完成时触发，不适用于require子依赖
如何让自定义脚本支持参数传递？
Composer 原生不支持带参数的脚本调用（如 composer run my-script -- --env=prod），但可通过环境变量或解析 $argv 绕过限制。
最可靠方式是写一个封装 PHP 脚本，再在 scripts 中调用它：
#!/usr/bin/env php然后在
composer.json中注册："scripts": { "deploy": [ "@composer run-script --no-dev deploy:check", "php scripts/deploy.php" ], "deploy:check": "php -r \"if (!getenv('SCRIPT_ENV')) { exit(1); }\"" }
- 调用时用
SCRIPT_ENV=prod composer run deploy - 不要依赖
$argv直接读取，因为 Composer 启动 PHP 时可能不透传原始参数 - 若必须用 CLI 参数，建议改用
symfony/console单独构建命令行工具，而非强塞进 Composer Scripts
为什么 post-update-cmd 有时不执行？
根本原因：这个钩子只在显式执行 composer update 时触发，而 composer install 不会触发它——哪怕 vendor/ 不存在或 composer.lock 已过期。
典型误判场景：CI 环境中先 rm -rf vendor 再 composer install，期待 post-update-cmd 运行迁移或构建逻辑，结果静默跳过。
- 解决方案一：统一用
composer update --lock替代install（仅当 lock 文件存在且可信） - 解决方案二：把关键逻辑移到
post-install-cmd+post-update-cmd共享脚本中，并在脚本内用file_exists('composer.lock')判断上下文 - 注意：钩子执行失败（非零退出码）会导致整个 Composer 命令中止，调试时可加
|| true临时绕过，但上线前必须修复
实际项目里最容易被忽略的是钩子触发边界——它不等价于“每次依赖变化”，而是严格绑定到具体命令。想覆盖所有安装/更新路径，得组合多个钩子，或放弃钩子、改用 Makefile / npm scripts 做外层编排。
