composer run-script 是执行 composer.json 中 scripts 自定义命令的入口，但日常推荐直接用 composer xxx 简写；仅当脚本名含特殊字符或需禁用钩子时才需显式调用 run-script。
直接说结论： composer run-script 是执行 composer.json 中 "scripts" 定义的自定义命令的入口，但日常更推荐用 composer xxx 简写形式——它本质是 run-script 的语法糖，且自动支持事件钩子（如 pre-xxx / post-xxx）。
为什么 composer run-script 很少手动敲？
因为 Composer 会把 "scripts" 里的每个键名自动注册为一级命令。比如定义了：
"scripts": {
"test": "phpunit",
"build": "php build.php"
}
你完全可以直接运行：
composer test 或 composer build
而不用写冗长的 composer run-script test。后者只在两种场景真正有用：
- 脚本名含破折号、点号等非标准字符（如
"ci:lint"），此时composer ci:lint会报错，必须用composer run-script "ci:lint" - 想绕过自动触发的
pre-/post-钩子，显式调用原始脚本（run-script --no-dev或--no-hooks可控制）
run-script 的关键参数和陷阱
它不是简单转发命令，参数传递和环境行为容易出错：
-
composer run-script test -- --filter=MyTest：双横线--后的内容会透传给被调脚本（这里是 phpunit），漏掉它，参数会被 Composer 自己吃掉 -
run-script默认启用钩子；若只想跑脚本本身，加--no-hooks（注意不是--no-dev，后者只影响依赖安装） - 脚本中用
$argv或$_SERVER['argv']接收参数时，实际拿到的是 Composer 包装后的数组，索引可能偏移；建议改用$_SERVER['COMPOSER_ARGS']（Composer 4.0+ 提供）或统一用getenv('COMPOSER_ARGS') - Windows 下 CMD 里双引号必须全角或转义，否则
composer run-script "test -- --filter=..."会解析失败；PowerShell 更稳妥
调试脚本执行环境的实用技巧
当脚本行为和手动执行不一致（比如找不到二进制、路径错乱），本质是 Composer 启动时修改了 PATH 和工作目录：
- 所有脚本默认在项目根目录（
composer.json所在位置）执行，不是你当前 shell 路径 - Composer 会把
vendor/bin/加入PATH前置位，所以"cs": "php-cs-fixer"能直接调用，无需写完整路径 - 快速验证环境：在脚本里临时加
"debug": "pwd && echo $PATH && which php-cs-fixer"，再composer debug查看输出 - 如果脚本依赖当前 git 分支名等信息，别用
exec('git rev-parse --abbrev-ref HEAD')，改用shell_exec()并检查返回值——Composer 的执行上下文对信号和子进程更敏感
真正麻烦的从来不是怎么写 run-script，而是脚本里隐式依赖的环境变量、工作路径、PHP SAPI 模式（CLI 还是其他），以及钩子链中上一个脚本是否意外修改了全局状态。动手前先 composer run-script xxx --no-hooks 单独跑一次，能省掉大半排查时间。
