composer.json怎么添加注释_在composer配置文件中做笔记【说明】-composer-PHP中文网

composer.json 不支持 JSON 注释，因 RFC 8259 禁止注释，会导致 json_decode() 解析失败；可用 scripts 做可执行“活注释”、extra 存元信息、README.md 写详细说明，并通过 CI 检查防止注释误入。

composer.json怎么添加注释_在composer配置文件中做笔记【说明】

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 官方预留的扩展字段，类型为对象，完全由用户自定义结构，不参与依赖解析，也不会被任何命令拒绝——它就是干这个用的。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(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 的简洁性是优势，不是缺陷。强行给它加注释，就像给螺丝刀装喷漆罐——功能没增加，反而容易拧歪。