<p>Composer 不提供内置脚本帮助功能，仅通过 composer.json 中 scripts.description 字段显示简要说明；真正的 --help 支持需在脚本内部手动实现，且必须用 composer run script -- --help 透传参数。</p>
Composer 没有内置的 composer run-script help 或类似“显示脚本用法”的功能——脚本本身不带 help 元数据，composer run --list 只列名字和描述（如果写了），不解释参数怎么传、支持哪些选项。
composer run --list 显示的 description 是唯一“官方帮助”
Composer 仅从 composer.json 的 scripts 字段读取键名和可选的字符串描述。例如：
"scripts": {
"test": {
"description": "Run PHPUnit with optional --filter or --group",
"script": ["@php", "vendor/bin/phpunit"]
}
}
此时 composer run --list 会显示：
test: Run PHPUnit with optional --filter or --group
但这个 description 完全靠手写，Composer 不校验、不解析、不强制要求。没写就空着，写错也不会报错。
- description 字段只在
composer run --list里出现，composer run test --help会直接失败（因为 test 脚本本身不是命令行工具） - 如果你用数组格式定义脚本（如
["@php", "test.php"]），description 不会自动继承 test.php 的 PHPDoc 或--help输出 - 想让
composer run test --help真正生效，得在test.php里自己实现参数解析和帮助文案
脚本内部怎么实现 --help 支持
真正能响应 --help 的，是脚本自身（比如 PHP 文件或 vendor/bin 下的二进制）。Composer 只负责把参数透传过去。所以关键在脚本逻辑里判断：
- PHP 脚本中检查
in_array('--help', $argv)或getenv('COMPOSER_ARGS')（Composer 4.0+ 提供） - 调用
vendor/bin/phpunit --help时，它自己的帮助页才出来；但注意：必须用composer run test -- --help（两个--），否则--help被 Composer 拦截 - Shell 脚本里用
case "$1" in --help) echo "Usage: ..."; exit 0;; esac，但需确保引号包裹完整，避免$1被空格截断
为什么不能依赖 composer run-script 自动提供帮助
因为 composer run-script 已被弃用（自 Composer 2.0），且它本质只是查找并执行字符串/数组定义，不做任何参数语义分析。它甚至不知道你写的 "test": "phpunit" 对应的是 PHPUnit，更不会转发 --help 到 phpunit 二进制。
-
composer run test -- --help和vendor/bin/phpunit --help行为一致，前提是脚本值正确指向可执行文件 - 如果脚本值是字符串
"test": "phpunit"，而phpunit不在$PATH中，就会报Command "phpunit" not found，连 help 都看不到 - 跨平台脚本（尤其含
&&、$()）在 Windows CMD 下大概率失效，help 文案再全也没用
真正可靠的做法：把帮助说明写进 composer.json 的 description 字段，并在脚本文件开头用注释或 if (isset($argv[1]) && $argv[1] === '--help') 手动输出。别指望 Composer 替你管这个。
