根本原因是 composer.json 中未正确定义或为空的 scripts 字段；脚本名须符合命名规范，且 scripts-descriptions（Composer 2.2+）可为 --list 提供描述，但不影响执行。

composer run-script --list 为什么有时不显示自定义脚本

根本原因通常是 composer.json 里没正确定义 scripts 字段，或该字段为空对象。Composer 只会扫描顶层 scripts 键下的键名作为可执行脚本名，不会递归或识别注释、变量占位符。

常见错误现象包括：命令返回空列表、只显示内置脚本（如 pre-install-cmd）、或报错 There are no scripts defined in the root package。

• 确认 composer.json 中存在 "scripts": { ... }，且不是 "scripts": {} 或被注释掉
• 脚本名不能含空格或特殊字符，仅支持字母、数字、下划线、中划线（如 build:prod 合法，build prod 不合法）
• 如果用 composer create-project 初始化项目，检查是否覆盖了原始 composer.json，导致脚本丢失

如何让 composer run-script --list 显示带描述的脚本

Composer 本身不原生支持脚本描述，但可通过在 scripts 中使用 @php -r "echo ..." 或调用外部工具（如 echo）实现伪描述 —— 实际上是把说明“打印出来”，而非元数据。

windows-shell-syntax

在 Windows 上执行终端命令，或对比 Windows 与 Linux 的 Shell 语法时使用。建议先检测当前 Shell 是 PowerShell 还是 cmd.exe，再给出相应命令……

下载

更可靠的做法是用 composer.json 的 scripts-descriptions（需 Composer 2.2+）扩展字段，但注意：该字段**仅用于 composer run-script --list 展示，不影响执行逻辑**。

• 添加 "scripts-descriptions" 对象，键名必须与 scripts 中完全一致：

  "scripts": {
    "test": "@php vendor/bin/phpunit"
  },
  "scripts-descriptions": {
    "test": "Run unit tests with PHPUnit"
  }

• 低版本 Composer（--list 仍只显示脚本名
• 描述文本不参与执行，也不校验是否存在对应脚本，拼写错误也不会报错

运行自定义脚本时找不到命令的典型原因

composer run-script xxx 执行失败，提示 Command not found 或 Script xxx handling the xxx event returned with error code，往往不是脚本没列出来，而是执行环境缺失依赖或路径问题。

• 脚本中调用的二进制文件（如 phpcs、phpstan）未安装在 vendor/bin/ 下，或未加 ./vendor/bin/ 前缀
• 使用 php 调用时未指定完整路径（如 php ./script.php），而当前工作目录不是项目根目录
• Windows 下脚本值含 sh 或 bash 命令（如 sh -c "..."），默认不可执行；应改用 @php -r 或跨平台工具
• 脚本值以 @ 开头（如 @php）表示调用 Composer 内置命令处理器，此时不走 shell，无法使用管道、重定向等 shell 特性

调试脚本执行过程的实用技巧

光看 --list 不足以验证脚本是否真能跑通，得观察实际执行时的行为和上下文。

• 加 -v（verbose）参数：例如 composer run-script build -v，会显示完整命令行、工作目录、环境变量前缀
• 临时插入调试语句：在脚本值开头加 echo "RUNNING: $(pwd)"; （Linux/macOS）或 echo "RUNNING: %cd%（Windows）
• 用 composer config bin-dir 确认 vendor/bin 路径是否被自定义过，避免硬编码路径失效
• 注意 run-script 默认在项目根目录执行，但某些 IDE 或 CI 工具可能在子目录触发，导致相对路径出错

实际项目中，最易被忽略的是 scripts-descriptions 的版本兼容性，以及 Windows 下对 shell 语法的天然排斥 —— 很多本地测试通过的脚本，在 CI 的 Linux 环境或队友的 Windows 机器上静默失败。