必须使用 -- 分隔符透传参数，如 composer run-script build -- --env=prod；PHP 脚本通过 $argv 接收，$argv[1] 起为原始参数，需自行解析；其他写法均会被 Composer 拦截或忽略。
composer run-script 怎么传参数给 PHP 脚本
直接在命令行里加 -- 分隔符，后面跟的参数会原样透传到脚本中，不会被 Composer 解析。这是唯一可靠的方式，其他写法（比如 composer run-script foo --arg=val）会被 Composer 拦截或忽略。
例如你的 scripts 定义是：
"scripts": {
"build": "php build.php"
}
执行时要传 --env=prod，就得这样写：
composer run-script build -- --env=prod
注意：中间两个短横线 -- 是必须的，缺一不可；它告诉 Composer “后面的都别碰，全交给脚本”。
PHP 脚本里怎么接收这些参数
Composer 不做任何参数解析或转换，只是把 -- 后面的内容原样塞进 $argv。所以你的 build.php 需要自己处理：
-
$argv[0]是脚本路径（如build.php） -
$argv[1]开始才是你传的参数（如--env=prod） - 推荐用
getopt()或更轻量的parse_str(implode('&', array_slice($argv, 1)), $opts)快速提取键值对
简单示例：
$opts = [];
foreach (array_slice($argv, 1) as $arg) {
if (str_starts_with($arg, '--')) {
[$key, $val] = explode('=', substr($arg, 2), 2) + ['', ''];
$opts[$key] = $val ?: true;
}
}
// $opts['env'] === 'prod'
常见踩坑：参数被 Composer 吃掉或报错
以下写法都会失败：
-
composer run-script build --env=prod→--env被 Composer 当作自身选项，报错“unrecognized option” -
composer run-script build -e prod→ 短参数不支持，且没--分隔，直接被忽略 -
composer run-script build "--env=prod"→ 引号没用，仍会被 Composer 解析
唯一正确姿势就是：-- 单独成项，后面所有内容才安全透传。
Windows 下额外注意空格和引号
PowerShell 或 cmd 中，如果参数含空格（比如 --message="hello world"），必须用双引号包裹整个参数项，并确保 -- 仍独立存在：
composer run-script build -- "--message=hello world"
否则 Windows 命令行可能把空格当作分隔符，导致 $argv 错位。Mac/Linux 一般无此问题，但统一加引号更稳妥。
真正容易被忽略的是：-- 不是可选语法糖，它是 Composer 参数透传的开关，漏掉就等于没传参。
