Composer 官方不支持 scripts 字段添加 description，脚本描述需通过语义化命名（如 dev:clear-cache）、help 脚本或 README 文档实现，命名即契约，应优先保证清晰稳定。
composer.json 里 scripts 字段不支持直接写 description
Composer 官方没提供给 scripts 条目加描述的字段，composer.json 的 scripts 是纯键值对映射（脚本名 → 命令），没有元数据支持。你看到的 composer list 输出里某些脚本带说明，其实是靠「脚本名本身带语义」或「命令行工具自动解析」实现的，并非 Composer 解析了某个 description 字段。
用 script name 模拟描述（最简单有效）
Composer 会把 scripts 的 key 当作命令名显示在 composer list 中，所以命名时直接嵌入说明性文字就行。比如：
"scripts": {
"dev:clear-cache": "php artisan cache:clear",
"test:run-with-coverage": "vendor/bin/phpunit --coverage-html coverage",
"build:docker-dev": "docker-compose build app"
}
运行 composer list 就能看到这些带冒号分隔、语义清晰的条目，比写一堆注释更实用。注意：冒号不是语法要求，只是社区约定，方便人眼归类；Composer 不关心它，只认 key 名字。
用 inline 注释 + 自定义 help 脚本（适合复杂项目）
如果团队需要更正式的说明（比如参数说明、执行前提），可以额外加一个 help:xxx 脚本，手动输出帮助文本：
"scripts": {
"dev:clear-cache": "php artisan cache:clear",
"help:dev:clear-cache": "echo 'Clears Laravel cache (config, views, routes) — safe to run in dev)'"
}
然后运行 composer help:dev:clear-cache 查看说明。这种方式可控性强，但得靠人维护同步，容易过期。几个要点：
-
help:前缀是惯例，不是强制，只要名字不冲突就行 - 别用
echo以外的 shell 特性（如管道、变量展开），否则 Windows 用户可能执行失败 - 如果脚本本身是 PHP 文件，推荐改用
php scripts/help-dev-clear-cache.php，可做跨平台兼容和格式美化
第三方插件方案（不推荐轻量项目）
像 hirak/prestissimo 或 consolidation/robo 这类工具能增强脚本管理能力，但它们解决的是「任务编排」问题，不是「加描述」。真正想让 composer list 显示自定义说明，目前唯一可靠路径是：靠命名规范 + 配合文档 README.md 同步更新。很多团队在 README.md 里维护一份「常用 composer 脚本速查表」，比塞进 JSON 更易读、可维护。
真正容易被忽略的是：脚本名一旦写进 CI/CD 配置或同事的 shell alias 里，就变成了接口契约——改名成本远高于加一行注释。所以命名第一，描述第二，插件第三。
