Composer 通过同级的 scripts-descriptions 字段为 scripts 中的命令添加描述，其 key 必须与 scripts 命令名完全一致；需 Composer 2.2+，且 JSON 格式正确、无拼写错误。
composer.json 里 scripts 字段的 description 怎么加
Composer 不支持直接在 scripts 数组里为每个脚本写描述字段——它原生只认命令名和对应执行内容。所谓“自定义命令描述”，其实是靠 scripts-descriptions 这个特殊键实现的，必须和 scripts 同级、独立声明。
正确写法是：
{
"scripts": {
"test": "phpunit",
"build": "php build.php"
},
"scripts-descriptions": {
"test": "Run unit tests with PHPUnit",
"build": "Compile assets and generate production files"
}
}
注意：scripts-descriptions 的 key 必须和 scripts 中的命令名完全一致（包括大小写和连字符），否则 composer list 不会显示对应描述。
为什么 composer list 看不到我的描述
常见原因不是写法错，而是没满足两个硬性条件：
-
scripts-descriptions键名拼错了（比如写成script-descriptions或scripts_description） - 对应 script 名在
scripts中不存在（比如写了"lint"描述但没定义"lint"命令） - 用了 Composer 1.x 版本（
scripts-descriptions是 Composer 2.2+ 引入的，1.x 完全忽略该字段） - 运行了
composer install但没重新加载 autoload（极少，但改完composer.json后建议跑一次composer dump-autoload）
description 内容怎么写才实用
别写“执行构建”这种废话，重点说清三件事：做什么、对谁有用、有没有副作用。
- 用动词开头，比如
"Generate API docs using phpDocumentor"，而不是"API docs generation" - 提关键依赖或环境要求，比如
"Requires NODE_ENV=production and .env.local" - 标注是否修改文件，比如
"Writes to ./dist/ — safe to run in CI"或"Modifies composer.lock — avoid in shared environments" - 避免缩写，除非项目内已约定（如
CI可以，pkg就容易歧义）
想让描述支持中文或特殊符号要注意什么
JSON 标准本身支持 UTF-8，所以中文没问题，但有两点实际限制：
- 终端宽度有限，描述超过 ~60 字符会被截断（
composer list输出列宽固定），建议控制在 45 字以内 - 不要用换行符
\n或制表符\t，Composer 解析时会当空格处理，且破坏对齐 - 如果描述含双引号，必须转义：
"\"prod\" mode only"，否则 JSON 校验失败 - Emoji 可以用，但部分 CI 环境或老旧终端可能显示为方块，不推荐用于关键说明
描述再漂亮，也得先通过 composer validate；没通过就别指望 list 能显示出来。
