composer.json 不支持 JSON 注释，因 RFC 8259 禁止注释，会导致 json_decode() 解析失败；可用 scripts 做可执行“活注释”、extra 存元信息、README.md 写详细说明，并通过 CI 检查防止注释误入。
composer.json 本身不支持 JSON 注释
JSON 规范（RFC 8259）明确禁止注释，composer.json 是标准 JSON 文件，所以直接写 // 或 /* */ 会导致 composer install 报错：JSON decode error: Syntax error。这不是 Composer 的限制，是底层解析器（如 PHP 的 json_decode()）的硬性要求。
常见错误现象：加了注释后运行 composer update，终端直接报错退出，且不会提示具体哪一行——因为 JSON 解析器在遇到第一个非法字符（如 /）时就失败了。
- 别用编辑器自动补全的「JSONC」模式保存
composer.json，它会悄悄加注释，保存即埋雷 - VS Code 默认对
.json文件启用 JSON 验证，但对composer.json有时会误判为 JSONC，需手动确认右下角语言模式是JSON而非JSON with Comments - CI/CD 流水线里一旦出错，往往卡在依赖安装阶段，排查时容易忽略本地文件已被“静默注释化”
用 scripts 字段做可执行的“活注释”
把说明性文字转成带上下文的命令描述，既合法又实用。Composer 允许在 scripts 中定义任意命名的命令，这些命令不会被自动执行，但能被 composer run 触发，且字段值天然支持字符串说明。
例如你想备注「这个包只用于开发环境，上线前必须移除」：
"scripts": {
"note-dev-only": "echo '⚠️ package-vendor/dev-tool is dev-only — remove before prod deploy'"
}
之后执行 composer run note-dev-only 就能立刻看到提醒。比藏在 README 里更靠近代码，也比注释更难被忽略。
-
scripts中的键名可自由命名，建议用note-前缀区分用途 - 值可以是任意 shell 命令，包括
printf、cat读取说明文件，甚至调用git blame查谁加的依赖 - 注意 Windows PowerShell 对单引号处理不同，跨平台项目建议统一用双引号包裹字符串
用 extra 字段存纯文本元信息
extra 是 Composer 官方预留的扩展字段，类型为对象，完全由用户自定义结构，不参与依赖解析，也不会被任何命令拒绝——它就是干这个用的。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
比如记录某个 require 的来龙去脉：
"extra": {
"notes": {
"monolog/monolog": "v2.10.0 required for PSR-3 logging in legacy API module",
"phpunit/phpunit": "v9.6.x pinned due to PHP 8.1 compat in test suite"
}
}
虽然 Composer 不会读取它，但团队成员用 jq '.extra.notes' composer.json 或 IDE 插件就能快速查到上下文。
-
extra不影响性能，不参与锁文件生成，也不改变安装行为 - 避免在
extra里放敏感信息（如密钥），它会随composer.json一起提交到仓库 - 如果项目有自定义脚本或 CI 工具，可以用
composer config extra.notes.monolog/monolog读取特定条目
真正需要解释时，优先改 README.md
配置文件不是文档载体。composer.json 的核心职责是声明依赖和运行时行为，所有关于「为什么选这个版本」「替代方案对比」「升级风险」的内容，都该放在 README.md 的「Dependencies」章节里。
这样做的好处是：文档可渲染、可链接、可搜索、可版本对比，还能配图或表格；而塞进 JSON 里的文字，只能靠人眼硬扫，还容易因格式错误导致整个项目瘫痪。
- 在 README 中用锚点链接到对应依赖行，例如：
[monolog/monolog](https://github.com/example/project/blob/main/composer.json#L24) - CI 流程中可加检查：用
grep -q "//" composer.json防止注释误入 - 最省事的折中：把临时笔记写在
composer.json同目录下的COMPOSER_NOTES.md，Git 提交时一并带上
JSON 的简洁性是优势，不是缺陷。强行给它加注释，就像给螺丝刀装喷漆罐——功能没增加，反而容易拧歪。
