如何在使用Composer时利用scripts-descriptions为自定义指令添加文档说明-composer-PHP中文网

scripts-descriptions 是 composer 的配置项，用于为 composer.json 中 scripts 下的自定义脚本提供人类可读描述，仅影响 composer list 和 composer run --list 输出，需与 scripts 同级且脚本名严格匹配。

如何在使用composer时利用scripts-descriptions为自定义指令添加文档说明

scripts-descriptions 是什么，它在哪起作用

scripts-descriptions 是 Composer 的一个特殊配置项，用于给 composer.json 中定义的自定义脚本（即 scripts 下的命令）添加人类可读的说明。它本身不改变任何行为，只影响 composer list 和 composer run --list 的输出——没有它，自定义脚本只会显示为无描述的命令名。

如何正确声明 scripts-descriptions 配置

必须将 scripts-descriptions 作为顶层字段写在 composer.json 里，与 scripts 同级；键名需完全匹配 scripts 中的脚本名，值为字符串描述。大小写、空格、连字符都必须严格一致。

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

错误写法："scripts-descriptions": { "post-install-cmd": "Runs after install" } —— 如果 scripts 里实际是 "post-install-cmd"，这没问题；但如果脚本名是 "post-install" 或 "postInstall"，就完全不生效

正确示例：

{
  "scripts": {
    "dev-start": "php -S localhost:8000 -t public",
    "test-ci": "vendor/bin/phpunit --no-coverage"
  },
  "scripts-descriptions": {
    "dev-start": "Start local dev server on port 8000",
    "test-ci": "Run PHPUnit without coverage (fast CI mode)"
  }
}

描述文本支持空格和标点，但不要换行或 JSON 注释（JSON 不允许）

scripts-descriptions 不生效的常见原因

最常遇到的问题不是语法错，而是位置或匹配问题。Composer 只在加载 composer.json 时读取该字段，且不做容错校验：名字对不上就静默忽略。

scripts-descriptions 写在 scripts 对象内部（比如当成子字段）→ 完全无效
脚本名用了别名（如通过 composer run test 调用），但 scripts-descriptions 里写的是别名而非真实脚本名 → 不显示
项目依赖了其他包，而你在根 composer.json 里写了 scripts-descriptions，却期望它出现在 vendor 包的脚本列表中 → 不可能，它只作用于当前项目的 scripts
运行 composer list 但没看到你的描述？先确认是否执行的是当前项目目录下的命令（不是全局或子目录）

它和 script aliases 的关系

Composer 5.0+ 支持 scripts 中用数组定义 alias（例如 "test": ["@test-ci", "@test-static"]），但 scripts-descriptions 只能描述“真实脚本名”，不能为 alias 单独加描述。alias 自身不会出现在 composer list 输出中，也不会触发对应描述。