Composer scripts-descriptions怎么写 自定义命令描述信息【美化】

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 能显示出来。