Composer 2.5+ 可用 scripts-descriptions 字段为自定义脚本添加说明，使其在 composer run --list 中显示；该字段需与 scripts 同级，仅对非生命周期钩子脚本生效，键名须严格匹配。
composer run 的 --list 不显示自定义脚本说明怎么办
Composer 原生不支持为自定义脚本（如 "dev:setup"）添加 help 文本，composer run --list 只会列出脚本名和类型（event 或 script），不会展示任何描述。这不是配置遗漏，是功能缺失。
用 scripts-descriptions 字段补充说明（仅限 Composer 2.5+）
从 Composer 2.5 开始，可选字段 scripts-descriptions 允许为每个自定义脚本加一行简短说明，会被 composer run --list 一并输出。但注意：它只对手动调用型脚本生效（即非生命周期钩子），且必须与 scripts 同级：
{
"scripts": {
"dev:setup": ["composer install", "php generate-config.php"],
"clear-cache": ["php clear-cache.php"]
},
"scripts-descriptions": {
"dev:setup": "初始化开发环境：装依赖 + 生成配置",
"clear-cache": "清空应用缓存目录"
}
}
-
scripts-descriptions中的键必须严格匹配scripts里的脚本名 - 生命周期钩子（如
post-install-cmd）写在这里无效，它们不参与composer run列表 - 旧版 Composer（
脚本内部用 --help 参数模拟帮助（推荐补位方案）
更可靠、兼容所有版本的做法，是在 PHP 脚本里自己处理 --help 或 -h 参数。例如 scripts/dev-setup.php 开头加：
#!/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";
echo "\nOptions:\n";
echo " --force 跳过确认，强制重写配置\n";
exit(0);
}
require __DIR__ . '/vendor/autoload.php';
// …后续逻辑
- 调用时用
composer run dev:setup -- --help（双横线后参数透传给脚本） - 避免在 shell 命令中硬编码 help 输出，否则
composer run --list仍看不到 - 这对需要参数校验或用户交互的脚本尤其必要——比如带
--env=prod的部署脚本
别把 help 当成文档，关键逻辑得写进 README.md
再完善的 help 提示也替代不了项目级说明。真实协作中容易被忽略的是：
-
scripts-descriptions最多一行，无法说明前置条件（如“需先配置 .env”）或副作用（如“会删除 storage/logs/*”） - CI 环境里没人看
--help，靠的是文档和 git commit message - 如果脚本调用了外部命令（如
npm install），help 里不提依赖就等于没说清楚
最终建议：用 scripts-descriptions 做速查索引，用脚本内 --help 做参数指南，把上下文、权限、环境假设全写进 README.md#scripts。
