toolgarden.xyz
EN
JSONJSON5JSONC配置文件

JSON、JSONC、JSON5 有什么区别?配置文件该怎么选

从注释、尾逗号、引号、数字写法到解析器兼容性,逐项对比 JSON、JSONC 和 JSON5,并给出配置文件选型与转换为标准 JSON 的做法。

ToolGarden 推荐的工具优先在浏览器本地运行,文件和文本不必上传到服务器,适合更注重安全隐私的日常处理。

发布于 2026年7月2日更新于 2026年10月14日约 10 分钟作者 ToolGarden

同样是花括号加键值对,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、多种数字写法等。

语法对照表

特性JSONJSONCJSON5
// 和 /* */ 注释不允许允许允许
尾逗号不允许多数实现允许,取决于读取程序允许
单引号字符串不允许一般不允许允许
不带引号的 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 的四步

  1. 确认读取方:列出哪些程序会读这份文件,查文档确认它们是否支持注释或尾逗号。
  2. 在 JSON 修复页面粘贴原文,得到标准 JSON;同时记录被移除的注释内容,必要时迁移到文档或字段命名中。
  3. 检查数值类字段:十六进制、NaN、Infinity 是否被转换,转换后的含义是否仍然正确。
  4. 用 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 的新服务读取。做法是:先把注释里的信息迁移出去,再转换,最后验证。

  1. 阅读原文,把每条注释的含义记下来,放进 README 或单独的说明文件,比如“retries 为 0 表示不重试”。
  2. 把原文粘贴到 JSON 修复页面,得到标准 JSON。此时 key 会被加上双引号,字符串统一为双引号。
  3. 逐项检查数值:像 timeout: 1e3 这样的科学计数法会被规范化为 1000,核对是否仍符合预期。
  4. 把结果保存为新文件交给新服务,老文件保留作为带注释的“源文件”,并在其中说明“发布前需要转换”。
  5. 如果这套流程会经常发生,建议把转换放进构建脚本,用一个能识别字符串边界的 JSON5 库完成,而不是手工复制粘贴。

这样做的好处是,注释始终有一个归处,严格 JSON 又保持“干净”。代价是多了一个转换步骤,需要有人维护。如果团队觉得这个代价太高,说明这份配置本来就更适合换成 YAML 或 TOML。

什么时候不该使用宽松格式

  • 对外发布的接口或开放数据:消费方不可控,必须输出严格 JSON。
  • 需要签名、哈希或逐字节比较的内容:宽松语法让同一语义有多种写法,哈希会不一致。
  • 安全相关配置:解析器之间的差异可能导致一方认为某个字段存在而另一方不认,应使用最严格、最普遍的格式。

用正则清理注释,为什么不推荐

不少人会写一个正则去掉 // 注释再交给 JSON.parse。问题是字符串里可能就有 // 开头的内容,例如 URL “https://example.com”,粗糙的正则会把它从中间截断。如果你确实要在脚本里处理,必须是能识别字符串边界的解析方式。要快速验证某条正则能否匹配到你想删的片段,可以先在正则测试页面试验;但对一次性的清理,直接用修复页面更省事,也更不容易出错。

常见问题

Q.JSONC 是一种正式标准吗?

不是。JSONC 是“带注释的 JSON”的统称,没有独立的官方规范。VS Code、TypeScript 等工具各自规定了它们接受的语法,通常包括注释,部分还容忍尾逗号。使用前要以读取它的程序的文档为准。

Q.package.json 可以写注释吗?

不可以。npm 等包管理器按标准 JSON 读取 package.json,注释和尾逗号都会导致解析失败。需要说明的内容可以放在 README 或其他文档中。

Q.JSON5 比 JSON 更好吗?

取决于场景。JSON5 对手写配置更友好,但它不是所有语言和工具都默认支持的格式。用于数据交换时,严格 JSON 的兼容性更好。

Q.转换成标准 JSON 会丢失什么?

注释会丢失;十六进制等数字会以十进制输出;Infinity 和 NaN 会变成 null;写法上的引号和缩进风格会被统一。数据的结构和普通字符串、数字、布尔值保持不变。

Q.ToolGarden 的格式化页面支持哪些写法?

页面先按标准 JSON 解析,失败后回退到 JSON5 解析,所以注释、尾逗号、单引号、不带引号的 key 都能读入,输出总是标准 JSON。

Q.给 .json 文件加注释会有什么风险?

最大的风险是“某个工具读不了”:你的编辑器可能完全正常,而 CI 里的某个脚本、第三方服务或后端解析器会直接报错。上线前用只认标准 JSON 的方式验证一次。