scripts-descriptions 不起作用，因为它是社区约定的注释方式，Composer 不解析该字段；唯一官方支持的描述机制是在 scripts 条目中同级配置 description 字符串，仅在 composer run --list 中显示。

Composer 的 scripts 本身不支持直接为每个脚本添加描述字段，scripts-descriptions 并非 Composer 原生配置项——它只是社区约定的一种注释方式，靠人工维护，不会被 Composer 解析或使用。

为什么 scripts-descriptions 不起作用？

Composer 只读取 scripts 和 scripts-dev 下的键值对作为可执行命令，其余字段（包括 scripts-descriptions、extra 中的任意自定义键）均被忽略。运行 composer list 或 composer run --list 时，你看到的脚本说明全部来自脚本命令本身的注释（如 PHPDoc 风格）或 description 字段（仅限于某些插件或自定义工具）。

真正生效的脚本描述方式：用 description 键 + composer run --list

从 Composer 2.5 开始，scripts 中的每个条目可选配 description 字段（需为字符串），该字段会被 composer run --list 显示出来，是目前唯一官方支持的内建描述机制。

• description 必须与脚本命令同级，且只能是字符串
• 只在 composer run --list 中显示，composer list 仍不显示（后者只列出内置命令）
• 不支持多行或 Markdown，纯文本即可

{
    "scripts": {
        "test": {
            "script": "@php vendor/bin/phpunit",
            "description": "Run unit tests with PHPUnit"
        },
        "cs-fix": {
            "script": "@php vendor/bin/php-cs-fixer fix",
            "description": "Auto-fix coding standards violations"
        }
    }
}

兼容旧版 Composer 或需要更丰富帮助时：用 ## 注释 + 自定义命令封装

若项目仍在用 Composer composer list 中也体现说明，可行做法是把脚本

逻辑移到独立 PHP 文件中，并用 PHPDoc 注释；再通过 composer run 调用它。此时可配合 composer list 插件（如 hirak/prestissimo 不适用，推荐 roave/composer-dev-dependencies 的辅助能力有限），但最可靠的是自己写一个简易 help 命令：

• 在 scripts 中加一条 "help:scripts"，调用 php scripts/help.php
• scripts/help.php 手动输出带说明的脚本列表（读取 composer.json 或硬编码）
• 避免依赖外部包，保持最小侵入性

{
    "scripts": {
        "help:scripts": "php scripts/help.php"
    }
}

容易被忽略的关键点

很多人试图在 extra 里塞 scripts-descriptions 并期望 IDE 或 CLI 自动识别——这不会生效。IDE（如 PHPStorm）对 Composer 脚本的提示，依赖的是 scripts 结构 + description 字段（2.5+），不是注释也不是 extra。如果你看到某项目“有描述”，大概率是用了 2.5+ 的 description，或者团队自己维护了一份 README 脚本清单。