同样是花括号加键值对,tsconfig.json 里可以写注释,package.json 里却不行;.babelrc 可以不给 key 加引号,接口响应却绝对不行。这些差异背后是三种相关但不同的格式:JSON、JSONC 和 JSON5。本文先讲清三者各自允许什么,再给出“这个文件该用哪种”的判断方法,最后演示如何把宽松写法转换成任何解析器都认的标准 JSON。
一句话区分
- JSON:严格的数据交换格式,由 ECMA-404 和 RFC 8259 定义。不允许注释、尾逗号、单引号。
- JSONC:“带注释的 JSON”,没有独立的正式规范,是一种约定:在 JSON 基础上允许 // 和 /* */ 注释,常见实现(如 VS Code 的设置文件、TypeScript 的 tsconfig)通常还容忍尾逗号。具体容忍什么取决于读取它的程序。
- JSON5:有公开规范(json5.org)的 JSON 超集,借鉴 ECMAScript 5 的写法,允许注释、尾逗号、单引号、不带引号的 key、多种数字写法等。
语法对照表
| 特性 | JSON | JSONC | JSON5 |
|---|---|---|---|
| // 和 /* */ 注释 | 不允许 | 允许 | 允许 |
| 尾逗号 | 不允许 | 多数实现允许,取决于读取程序 | 允许 |
| 单引号字符串 | 不允许 | 一般不允许 | 允许 |
| 不带引号的 key | 不允许 | 一般不允许 | 允许(需是合法标识符) |
| 字符串内换行(行尾反斜杠) | 不允许 | 一般不允许 | 允许 |
| 十六进制数 0x1F | 不允许 | 不允许 | 允许 |
| +1、.5、5. 等数字写法 | 不允许 | 不允许 | 允许 |
| Infinity、NaN | 不允许 | 不允许 | 允许 |
| 规范状态 | ECMA-404 / RFC 8259 | 约定,无统一规范 | 公开规范 json5.org |
| 常用扩展名 | .json | .jsonc 或沿用 .json | .json5 |
三种格式分别出现在哪里
| 场景 | 典型文件 | 建议的格式 | 原因 |
|---|---|---|---|
| HTTP 接口、数据库、消息队列 | API 响应、事件载荷 | 严格 JSON | 跨语言互通,解析器行为一致 |
| npm 包信息 | package.json | 严格 JSON | 包管理器按标准 JSON 读取,写注释会报错 |
| 编辑器与编译器配置 | tsconfig.json、VS Code 设置 | JSONC | 这些工具明确支持注释,便于解释为什么开某个选项 |
| 需要大量注释的手写配置 | 工具链配置、规则文件 | JSON5 或 YAML | 可读性更好;先确认读取它的程序真的支持 |
| 被多个语言/工具链共享的配置 | 跨团队的公共配置 | 严格 JSON | 越宽松的格式,越容易有某个消费方读不了 |
选择时把握一个原则:写入方想宽松,读取方说了算。只有当“读取这份文件的所有程序”都明确支持某种语法,才能在文件里使用它。
实战:把一份 tsconfig 风格的 JSONC 转成标准 JSON
下面这份配置有注释、尾逗号,还有一个本来就不合法的写法。把它粘贴到 JSON 格式化页面,页面会先尝试标准解析,失败后用 JSON5 解析并输出标准 JSON。
{
// 编译选项
"compilerOptions": {
"target": "ES2020",
"strict": true, /* 打开全部严格检查 */
"paths": { "@/*": ["./src/*"], },
},
"include": ["src"],
}输出(注意注释和尾逗号都消失了,缩进为 2 个空格):
{
"compilerOptions": {
"target": "ES2020",
"strict": true,
"paths": {
"@/*": [
"./src/*"
]
}
},
"include": [
"src"
]
}这意味着:格式化和修复的输出是标准 JSON,适合发给只认严格 JSON 的程序,但会丢失注释。如果你要保留注释继续维护,不要用输出覆盖原文件,把它另存为一份“发布用”的副本。
JSON5 专属写法转换后的变化
JSON5 允许的一些写法在转换成标准 JSON 时,含义会发生变化,这是迁移时最容易被忽视的部分。
// JSON5 输入
{
name: 'it\'s',
mask: 0x1F,
ratio: .5,
retries: +3,
ceiling: Infinity,
missing: NaN,
}// 转成标准 JSON 后
{
"name": "it's",
"mask": 31,
"ratio": 0.5,
"retries": 3,
"ceiling": null,
"missing": null
}- 十六进制 0x1F 变成十进制 31,原来按位掩码的“可读性”丢了,建议在字段名或文档里补充说明。
- +3 的加号、.5 的省略前导零都会被规范化,数值不变,写法改变。
- Infinity 和 NaN 在标准 JSON 里没有对应写法,输出时会变成 null,信息丢失。这种值应在源数据中改为明确的 null、字符串或具体数值。
- 字符串里的转义保持语义不变,单引号字符串转为双引号字符串,内部的双引号会被加上反斜杠。
一个容易踩的坑:宽松解析会放过非法转义
标准 JSON 要求反斜杠成对。JSON5 的规则更宽松,它会把不认识的转义当作字符本身。结果是:Windows 路径 C:\Users\bob 在严格解析下报错,在宽松解析下却不报错,反而被读成 CUsers 加一个退格符。格式化页面显示成功,数据实际上已经变形。所以只要内容里有反斜杠,就要在转换后核对字符串值,并把源头改成 C:\\Users\\bob。
如何迁移:从 JSON5 / JSONC 到标准 JSON 的四步
- 确认读取方:列出哪些程序会读这份文件,查文档确认它们是否支持注释或尾逗号。
- 在 JSON 修复页面粘贴原文,得到标准 JSON;同时记录被移除的注释内容,必要时迁移到文档或字段命名中。
- 检查数值类字段:十六进制、NaN、Infinity 是否被转换,转换后的含义是否仍然正确。
- 用 JSON Schema 或真实的读取程序做一次验证,再替换线上文件。
如何选择:一个简单的决策流程
- 文件会被不同语言或第三方程序读取?用严格 JSON。
- 文件是编辑器或编译器的配置,并且官方文档明确支持注释?用 JSONC,保持 .json 或使用 .jsonc 扩展名,以工具要求为准。
- 纯手写、大量需要解释的配置,且你完全控制读取程序?可以考虑 JSON5,或者直接改用 YAML、TOML 这类本来就支持注释的格式。
- 需要程序化修改并写回文件?优先用严格 JSON,因为多数库在写回时会丢失注释。
最后补充一个现实的判断标准:如果你无法列出“所有会读取这份文件的程序”,那就当作它们中有严格解析器。无法确定读取方的文件,宁可多做一步转换,也不要赌运气。把注释写进相邻的文档,把文件本身保持成最朴素的 JSON,是长期维护成本最低的做法。
不同语言和工具对宽松语法的支持
“我的编辑器能打开”不代表“所有程序能读取”。下面按读取方整理了常见情形,帮助你判断一个带注释的 .json 文件会在哪里出问题。
| 读取方 | 对注释和尾逗号的态度 | 说明 |
|---|---|---|
| 浏览器和 Node.js 的 JSON.parse | 都不接受 | 标准实现,遇到注释或尾逗号直接抛错 |
| Python 标准库 json | 都不接受 | 读取这类文件需要先清理,或改用支持宽松语法的第三方库 |
| jq 等命令行工具 | 默认不接受 | 按严格 JSON 解析 |
| TypeScript 编译器读取 tsconfig.json | 接受 | 这是编译器对该配置文件的特殊处理,不适用于其他 JSON 文件 |
| VS Code 的设置和任务文件 | 接受 | 这些文件按带注释的 JSON 读取 |
| npm 读取 package.json | 不接受 | 按标准 JSON 读取 |
| json5 这类解析库 | 接受(并支持更多写法) | 需要在代码里主动选用它,而不是 JSON.parse |
这张表的重点不是背下每一行,而是养成一个习惯:每当你想在某个 .json 文件里加注释,先问一句“有哪些程序会读它”。其中只要有一个是严格解析器,注释就会在那里引发错误,而且往往出现在你最不方便调试的环境,比如 CI 或线上。
迁移示例:把 JSON5 风格配置改造成严格 JSON
假设团队有一份历史遗留的配置,用了单引号、裸 key 和注释,现在要交给一个只认严格 JSON 的新服务读取。做法是:先把注释里的信息迁移出去,再转换,最后验证。
- 阅读原文,把每条注释的含义记下来,放进 README 或单独的说明文件,比如“retries 为 0 表示不重试”。
- 把原文粘贴到 JSON 修复页面,得到标准 JSON。此时 key 会被加上双引号,字符串统一为双引号。
- 逐项检查数值:像 timeout: 1e3 这样的科学计数法会被规范化为 1000,核对是否仍符合预期。
- 把结果保存为新文件交给新服务,老文件保留作为带注释的“源文件”,并在其中说明“发布前需要转换”。
- 如果这套流程会经常发生,建议把转换放进构建脚本,用一个能识别字符串边界的 JSON5 库完成,而不是手工复制粘贴。
这样做的好处是,注释始终有一个归处,严格 JSON 又保持“干净”。代价是多了一个转换步骤,需要有人维护。如果团队觉得这个代价太高,说明这份配置本来就更适合换成 YAML 或 TOML。
什么时候不该使用宽松格式
- 对外发布的接口或开放数据:消费方不可控,必须输出严格 JSON。
- 需要签名、哈希或逐字节比较的内容:宽松语法让同一语义有多种写法,哈希会不一致。
- 安全相关配置:解析器之间的差异可能导致一方认为某个字段存在而另一方不认,应使用最严格、最普遍的格式。
用正则清理注释,为什么不推荐
不少人会写一个正则去掉 // 注释再交给 JSON.parse。问题是字符串里可能就有 // 开头的内容,例如 URL “https://example.com”,粗糙的正则会把它从中间截断。如果你确实要在脚本里处理,必须是能识别字符串边界的解析方式。要快速验证某条正则能否匹配到你想删的片段,可以先在正则测试页面试验;但对一次性的清理,直接用修复页面更省事,也更不容易出错。