Composer 不支持 scripts-descriptions 配置项，该字段非官方定义；正确方式是在 scripts 命令值同一行开头用 # 添加描述注释（仅 Composer ≥2.2 支持），或通过 extra 字段配合外部脚本实现稳定展示。

Composer 的 scripts-descriptions 并不是官方支持的配置项，直接写在 composer.json 里不会生效 —— 这是很多人踩坑的第一步。

为什么 scripts-descriptions 不起作用？

Composer 官方文档中从未定义过 scripts-descriptions 这个字段。它既不是根级配置项，也不被 composer install 或 composer run 解析。你看到的某些博客或旧项目里出现这个写法，大概率是误传、拼写错误，或是混淆了第三方插件（如 hirak/prestissimo 或自研脚本管理工具）的私有约定。

• Composer 原生只识别 "scripts" 下的命令名和对应动作
• 描述信息必须通过其他方式补充：比如注释、README、或借助 composer list 的扩展机制
• 运行 composer run --list 或 composer list 时，它只会显示脚本名，不读取任何 “description” 字段

如何让自定义命令在 composer list 中显示描述？

唯一可靠的方式是使用 Composer 的 scripts + description 注释语法（仅限 Composer ≥ 2.2），但注意：这需要把描述写在脚本值的**同一行开头，用 # 注释**，且必须是 JSON 字符串字面量中的合法注释（实际是利用了 Composer 内部对 JSON 行注释的宽松解析）。

实操要点：

• 仅支持单行 # 注释，且必须紧贴脚本命令值之前（不能换行）
• 必须用双引号包裹整个字符串，# 后至少一个空格
• 该特性依赖 Composer 自身解析逻辑，并非 JSON 标准，低版本（

{
    "scripts": {
        "build": "# 构建前端资源并复制到 public/ # npm run build && cp -r dist/* public/",
        "test:unit": "# 运行 PHPUnit 单元测试 # vendor/bin/phpunit --testsuite=unit"
    }
}

执行 composer list 后你会看到：

...
build            构建前端资源并复制到 public/
test:unit        运行 PHPUnit 单元测试
...

更稳定、推荐的替代方案：用 composer.json 的 extra 区域手动维护描述

如果你需要生成文档、做 CI 提示、或集成到 IDE 插件里，硬编码注释不可靠。更可控的做法是把描述单独放在 extra.scripts-descriptions（名字任意）下，然后用脚本读取：

{
    "scripts": {
        "build": "npm run build && cp -r dist/* public/",
        "test:unit": "vendor/bin/phpunit --testsuite=unit"
    },
    "extra": {
        "scripts-descriptions": {
            "build": "构建前端资源并复制到 public/",
            "test:unit": "运行 PHPUnit 单元测试"
        }
    }
}

之后你可以写一个简单 PHP 脚本（例如 bin/composer-help.php）来输出带描述的列表：

 $desc) {
    printf("%-15s %s\n", $name, $desc);
}

再加一条 Composer 脚本："help:scripts": "php bin/composer-help.php"，就能随时查。

真正容易被忽略的是：Composer 的描述支持本质是“尽力而为”的非标准行为，别把它当契约。生产环境若需稳定展示，优先走 extra + 外部脚本，或者直接维护一份 SCRIPTS.md —— 毕竟人写的文档，比机器猜的注释靠谱得多。