Composer怎么配置Scripts描述信息_Composer如何给自定义脚本添加说明文字方便团队使用【技巧】-composer-PHP中文网

composer的scripts字段不支持注释，json语法本身禁止注释；推荐三种替代方案：①根级添加非标准字段scripts-descriptions供人阅读；②脚本命令内置--help支持运行时提示；③readme.md中手动维护scripts表格并随pr同步更新。

composer怎么配置scripts描述信息_composer如何给自定义脚本添加说明文字方便团队使用【技巧】

scripts 字段里不能直接写注释

Composer 的 composer.json 里 scripts 是个纯键值对对象，只认脚本命令，不解析注释。你加 // 或 /* */ 没用，JSON 语法本身就不支持注释，强行加会导致 composer validate 报错：JSON decode error: Syntax error。

想让团队知道 post-install-cmd 干啥、为啥要跑、有没有副作用，得绕开 JSON 注释限制。

用 scripts-descriptions 扩展字段配合 composer-unused 或自定义检查

官方没提供脚本描述字段，但社区有约定做法：在 composer.json 根级加一个非标准字段 scripts-descriptions，手动维护映射关系。它不会被 Composer 解析或执行，纯供人读。

scripts-descriptions 必须是对象，key 对应 scripts 中的脚本名，value 是字符串说明
团队成员查脚本用途时，直接 cat composer.json | grep -A 10 "scripts-descriptions" 就能扫到
CI 流程中可用 composer-unused（需 v2.5+）配合 --with-scripts-descriptions 检查描述是否缺失，避免“写了脚本但没人敢动”
注意：这个字段对 Composer 完全透明，删掉也不影响安装/脚本执行，但别拼错 key 名，否则工具识别不了

在脚本命令里塞 --help 或 -h 参数做运行时提示

如果脚本是 PHP 文件或可执行命令，最实在的办法是让它自己支持帮助输出。比如你的 dev:clear-cache 脚本指向 php bin/console cache:clear，那就改用封装函数：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

#!/usr/bin/env php
<?php if (in_array('--help', $argv) || in_array('-h', $argv)) {
    echo "Usage: composer run-script dev:clear-cache\n";
    echo "  Clears dev-mode caches, skips prod warmup.\n";
    echo "  ⚠️  Does NOT clear opcache — run 'opcache-reset' separately.\n";
    exit(0);
}
// 实际逻辑...

这样执行 composer run-script dev:clear-cache -- --help 就能弹出说明，比翻 JSON 更及时。

必须用 -- 分隔 Composer 参数和脚本参数，否则 --help 被 Composer 截获
PHP 脚本里用 $argv 判断，Shell 脚本用 $@ 和 case 匹配
别依赖 echo 长文本——有些 CI 环境会截断输出，关键约束写进注释或 README 里更稳

README.md 里同步维护 scripts 表格，用代码块列 command + description

文档落地最靠谱的方式，还是人肉同步。在项目根目录 README.md 里建个表格，字段就两列：Command 和 Description，每行对应一个 scripts 键。

示例片段：

| Command | Description |
|---------|-------------|
| <code>test</code> | Run PHPUnit with coverage; requires Xdebug enabled |
| <code>lint:php</code> | Run PHP-CS-Fixer in dry-run mode — auto-fixes on PR merge |
| <code>build:prod</code> | Compile assets, purge cache, generate proxy classes |