scripts-descriptions 不起作用，因为它是社区约定的注释方式，composer 不解析该字段；唯一官方支持的描述机制是在 scripts 条目中同级配置 description 字符串，仅在 composer run --list 中显示。
Composer 的 scripts 本身不支持直接为每个脚本添加描述字段，scripts-descriptions 并非 Composer 原生配置项——它只是社区约定的一种注释方式，靠人工维护，不会被 Composer 解析或使用。
为什么 scripts-descriptions 不起作用？
Composer 只读取 scripts 和 scripts-dev 下的键值对作为可执行命令，其余字段（包括 scripts-descriptions、extra 中的任意自定义键）均被忽略。运行 composer list 或 composer run --list 时，你看到的脚本说明全部来自脚本命令本身的注释（如 PHPDoc 风格）或 description 字段（仅限于某些插件或自定义工具）。
真正生效的脚本描述方式：用 description 键 + composer run --list
从 Composer 2.5 开始，scripts 中的每个条目可选配 description 字段（需为字符串），该字段会被 composer run --list 显示出来，是目前唯一官方支持的内建描述机制。
-
description必须与脚本命令同级，且只能是字符串 - 只在
composer run --list中显示，composer list仍不显示（后者只列出内置命令） - 不支持多行或 Markdown，纯文本即可
{
"scripts": {
"test": {
"script": "@php vendor/bin/phpunit",
"description": "Run unit tests with PHPUnit"
},
"cs-fix": {
"script": "@php vendor/bin/php-cs-fixer fix",
"description": "Auto-fix coding standards violations"
}
}
}
兼容旧版 Composer 或需要更丰富帮助时：用 ## 注释 + 自定义命令封装
若项目仍在用 Composer composer list 中也体现说明，可行做法是把脚本逻辑移到独立 PHP 文件中，并用 PHPDoc 注释；再通过 composer run 调用它。此时可配合 composer list 插件（如 hirak/prestissimo 不适用，推荐 roave/composer-dev-dependencies 的辅助能力有限），但最可靠的是自己写一个简易 help 命令：
- 在
scripts中加一条"help:scripts"，调用php scripts/help.php -
scripts/help.php手动输出带说明的脚本列表（读取composer.json或硬编码） - 避免依赖外部包，保持最小侵入性
{
"scripts": {
"help:scripts": "php scripts/help.php"
}
}
容易被忽略的关键点
很多人试图在 extra 里塞 scripts-descriptions 并期望 IDE 或 CLI 自动识别——这不会生效。IDE（如 PHPStorm）对 Composer 脚本的提示，依赖的是 scripts 结构 + description 字段（2.5+），不是注释也不是 extra。如果你看到某项目“有描述”，大概率是用了 2.5+ 的 description，或者团队自己维护了一份 README 脚本清单。
