Composer 原生不支持在 composer run --list 中显示自定义脚本说明，此功能直至 Composer 2.5 才通过 scripts-descriptions 字段实现；该字段需与 scripts 同级，键名严格匹配且仅对非生命周期脚本生效。
composer run --list 不显示脚本说明是正常行为
Composer 原生不支持为自定义脚本（如 "dev:setup"）在 composer run --list 中显示帮助文本。这不是配置写错了，而是功能上就不存在——直到 Composer 2.5 才通过 scripts-descriptions 字段补上这一环。
用 scripts-descriptions 添加简短说明（仅 Composer 2.5+）
该字段必须与 scripts 同级，键名严格匹配脚本名，且只对非生命周期钩子生效（post-install-cmd 这类无效）：
{
"scripts": {
"dev:setup": ["composer install", "php generate-config.php"],
"clear-cache": ["php clear-cache.php"]
},
"scripts-descriptions": {
"dev:setup": "初始化开发环境：装依赖 + 生成配置",
"clear-cache": "清空应用缓存目录"
}
}
-
scripts-descriptions的值只是纯文本，不支持 Markdown 或换行 - 键名大小写敏感，
"Dev:setup"和"dev:setup"不等价 - 旧版 Composer（
兼容所有版本的可靠方案：脚本内处理 --help
在 PHP 脚本开头手动解析 --help 或 -h 参数，是最稳妥的做法：
#!/usr/bin/env php
<?php if (in_array('--help', $argv) || in_array('-h', $argv)) {
echo "Usage: composer run dev:setup\n";
echo " composer run dev:setup -- --force\n\n";
echo "Options:\n";
echo " --force 跳过确认，强制重写配置\n";
exit(0);
}
<p>require <strong>DIR</strong> . '/vendor/autoload.php';
// …后续逻辑
- 注意
composer run dev:setup -- --force中的双横线--是分隔符，用于把参数透传给脚本 - 脚本里不能只依赖
$argv[1]，因为composer run会往前面加一堆内部参数 - 这种写法不依赖 Composer 版本，CI/CD 和本地开发表现一致
别把 description 当帮助文档用
description 字段只用于 Packagist 页面摘要展示，会被截断（通常只显示前 120 字），且不参与任何命令行交互：
- 它不会出现在
composer run --list输出里 - 填长文本没意义，填安装步骤更误导用户
- 真正要暴露给使用者的操作入口，应落在
scripts名称本身（比如test、build、serve）和配套的--help实现上
脚本的帮助信息容易被当成“锦上添花”，但实际是协作链路里最常被查阅的一环——漏掉它，别人第一次运行时就得去翻源码或 git log。
