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）来输出带描述的列表：
<?php
$data = json_decode(file_get_contents('composer.json'), true);
foreach ($data['extra']['scripts-descriptions'] ?? [] as $name => $desc) {
printf("%-15s %s\n", $name, $desc);
}
再加一条 Composer 脚本："help:scripts": "php bin/composer-help.php"，就能随时查。
真正容易被忽略的是：Composer 的描述支持本质是“尽力而为”的非标准行为，别把它当契约。生产环境若需稳定展示，优先走 extra + 外部脚本，或者直接维护一份 SCRIPTS.md —— 毕竟人写的文档，比机器猜的注释靠谱得多。
