Composer run-script怎么用 手动执行定义的脚本命令【指南】

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 单独跑一次，能省掉大半排查时间。