能否在JSON文件中添加注释？最佳实现方式是什么

原生RFC 8259标准的JSON是完全不支持注释语法的，不管是类C风格的//单行注释、/* */多行注释，还是自定义字段存注释的写法，都不属于标准JSON规范范畴：如果给严格遵循标准的JSON解析器喂带//注释的文件，会直接抛出语法解析错误。

你之前用过的两种写法，各自的适用场景和问题都很明确：

• //comments写法：这是JSON5、JSONC（带注释的JSON）这类JSON扩展变种支持的语法，不是标准JSON的能力。如果你的JSON文件只会在支持这类扩展语法的环境里用（比如做VSCode配置、用JSON5库加载项目配置），这种写法最直观，和普通代码的注释体验一致，也不会和业务数据混在一起，可读性很好。但只要要对接严格标准的JSON解析器，这种写法100%会解析失败。
• "_comment": "注释内容"写法：这种写法确实符合标准JSON语法，不会触发解析报错，但缺陷非常明显：它本质就是个普通的业务字段，解析完成后会直接出现在结果对象里，后续做字段遍历、数据校验的时候很容易被当成有效数据处理；同一个层级要写多条注释的话，还得手动给字段起不同的名字（比如_comment1、_comment2），维护成本很高，也没法方便地写多行结构化注释。

注释方案选择建议 #

没有通吃所有场景的“完美方案”，根据你的使用场景选就行：

• 如果能自己控制JSON的解析链路、不需要兼容严格标准解析器：直接用JSONC/JSON5格式是最优解，直接用//写单行注释、/* */写多行注释，把文件后缀改成对应的.jsonc/.json5，用匹配的解析库加载就可以，体验最好。
• 如果必须用严格标准的JSON、要兼容所有标准解析器：
  • 优先把注释和JSON数据分离，比如单独写配套的说明文档，或者在JSON Schema里写字段说明，不要把注释混在数据文件里，这是最稳妥不会出问题的方式。
  • 如果必须把注释和JSON存在同一个文件里，不要自己随便定义_comment这类字段，统一用$comment作为注释字段名——这是JSON Schema官方约定的注释字段，大部分JSON处理工具都会默认识别它是注释字段，不会当成业务数据处理，比自定义字段的通用性好很多。多行注释直接在字符串内换行即可，解析完成后记得在业务代码里过滤掉所有$comment字段，避免干扰正常逻辑。

提醒：不要用什么把注释塞到字段值末尾、重复键存注释这类野路子写法，可读性极差，后续维护非常容易出bug。

内容的提问来源于stack exchange，提问作者VBM46