JSON 能写注释吗
结论：RFC 8259 没有注释语法，`//` 与 `/* */` 都会让 JSON.parse 直接抛错。要写说明只有四条路：换 JSON5/JSONC、把备注塞进数据字段、写进 Schema 的 description，或改用 YAML。
结论：标准 JSON 里不要写注释；只给人编辑的本地配置改用 JSONC 或 JSON5，要跨系统传输时把说明搬进 JSON Schema 的 description，注释量大就直接换 YAML 或 TOML。
不能。
在任何标准 JSON 解析器里，下面这段都会抛错：
{
"port": 8080 // 本地开发用这个端口
}
浏览器控制台给出的错误是 SyntaxError: Unexpected token }——注释被当成了非法字符，解析器读到 / 就停下来了。
标准为什么故意不留注释
RFC 8259 的语法只有六种值：对象、数组、数字、字符串、true/false、null，没有任何注释产生式。
早期确实有人提议加，反对的理由很实在：注释一旦合法，就会有人拿它放解析指令，比如条件包含、模板变量，于是每个解析器都要实现自己的方言，跨语言互换立刻失效。JSON 的定位是「数据就是数据」，把可执行语义挡在门外。
所以注释不是「没人做」，而是「有意不做」。
想写说明，四条路可选
第一条：换 JSON5 或 JSONC。 这两个都是超集，//、/* */ 都支持，VS Code 的 settings.json、tsconfig.json 走的就是 JSONC。
代价是清晰的：JSON.parse 依然不认，接口、日志、消息队列通常只吃标准 JSON，注释会在传输链路的某一环被吃掉或直接报错。
第二条：把备注塞进数据。 常见写法是加一个 _comment 或 _note 键：
{
"_comment": "端口由运维统一分配，勿改",
"port": 8080
}
代价是污染数据模型，消费方必须知道要跳过哪些键，类型定义也要跟着多一个字段。
第三条：写进 JSON Schema。 description 本来就是给人和工具读的，校验器能输出它，IDE 能展示它，而它不进入数据本身。这是唯一既能长期维护、又不破坏兼容性的做法。
第四条：换配置文件格式。 如果这份文件天生就是给人改的，YAML 和 TOML 支持注释，比硬撑 JSON 更省事。
怎么判断该走哪条
| 场景 | 结论 |
|---|---|
| 要传给外部系统、走接口、进消息队列 | 不能注释，说明写进 Schema 或文档 |
| 只给人和编辑器看的配置 | 用 JSONC，别硬塞进 .json |
| 需要工具链全兼容，又要保留说明 | 标准 JSON + Schema description |
| 配置文件很长、注释很多 | 直接换 YAML |
常见问题
为什么 _comment 字段会污染数据模型？
因为它进入了数据本身。消费方必须知道要跳过哪些键，类型定义也要多出一个并非真实业务的字段。
是否能把说明写进 JSON Schema？
可以，而且这是唯一既能长期维护、又不破坏兼容性的做法。description 不进入数据，校验器能输出它，IDE 也能展示它。
JSONC 和 JSON5 能否直接交给 JSON.parse？
不能。JSON.parse 依然不认注释，接口、日志和消息队列通常只吃标准 JSON，注释会在链路的某一环被吃掉或直接报错。
相关工具
- JSON5 解析器：把带注释的配置粘进去，看解析后到底是什么结构
- JSON 格式化与校验：非法 JSON 会定位到具体行列，注释写在哪一行一眼能看出来