JSONJSON5JSONC配置文件

JSON vs JSONC vs JSON5：完整对比指南

JSON 是严格数据格式，JSONC 主要给配置文件增加注释，JSON5 则放宽了更多 JavaScript 风格语法。

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

发布于 2026年7月2日更新于 2026年7月20日约 9 分钟阅读作者 ToolGarden

JSON、JSONC、JSON5 看起来很像，但它们的定位不同。把它们混用，是很多解析报错的来源。

{
  // JSONC / JSON5 allow comments in some tools
  name: 'ToolGarden',
  tags: ['json', 'tools'],
}

核心区别

格式	是否标准 JSON	主要特点
JSON	是	严格、通用、适合接口和数据交换
JSONC	不是标准 JSON	常见于配置文件，允许注释，语法整体接近 JSON
JSON5	不是标准 JSON	更接近 JavaScript 对象字面量，允许单引号、尾逗号、未加引号 key 等

为什么 API 通常只接受标准 JSON？

API、数据库、消息队列和第三方平台需要跨语言解析。同一份数据可能会被 JavaScript、Java、Go、Python、Rust 等不同运行时读取。标准 JSON 的好处是规则少、歧义低、解析器行为更一致。

注释不是数据，发送给 API 后没有统一语义。
尾逗号、单引号、未加引号 key 在不同解析器中支持不一致。
NaN、Infinity 等值不是标准 JSON，很多后端会直接拒绝。
配置文件可以照顾人类阅读，接口数据更强调机器稳定解析。

为什么 tsconfig.json 可以写注释？

很多人第一次看到 tsconfig.json 里的注释会疑惑：文件扩展名明明是 .json，为什么还能写 // 注释？原因是 TypeScript 工具链按 JSONC 方式读取配置，它不是普通 JSON API 的解析规则。

文件或场景	常见格式	能否直接发给普通 API
tsconfig.json	JSONC 风格配置	不能假设可以
VS Code settings.json	JSONC 风格配置	不能假设可以
package.json	标准 JSON	通常可以
接口请求体	标准 JSON	应该使用标准 JSON

把 JSONC / JSON5 转成标准 JSON 的步骤

先解析宽松语法，确认内容能被 JSONC 或 JSON5 解析器理解。
移除注释、尾逗号，补齐未加引号的 key。
把单引号字符串转换成双引号字符串。
检查是否存在 NaN、Infinity、undefined 这类标准 JSON 不支持的值。
最后用标准 JSON 校验器再验证一遍。

什么时候用哪一个？

接口请求和响应：使用标准 JSON。
需要给人读的配置文件：可以考虑 JSONC，但要确认工具链支持。
希望写法更像 JavaScript：可以用 JSON5，但不适合直接发给普通 API。
要发送给后端、数据库或第三方系统：先转换成标准 JSON。

常见问题

Q.为什么 JSON 里不能写单引号字符串？

JSON 规范（RFC 8259）明确要求字符串必须用双引号包裹。这不是随意决定，而是为了让规则最简单、跨语言解析器行为一致。单引号在很多编程语言里也是合法字符串边界，但每种语言处理方式略有不同（Python 双引号和单引号等价，但 Java、C# 只能用双引号；JavaScript 里两者都行）。JSON 只允许双引号避免了这些差异。JSON5 允许单引号是因为它面向 JavaScript 开发者、优先考虑手写便利；一旦传给后端接口，就必须转成标准双引号 JSON。

Q.JSON 里可以用 NaN、Infinity 表示特殊数值吗？

不可以。标准 JSON 只允许有限的实数字面量（0、1、-3.14、1e10 等），不允许 NaN、Infinity、-Infinity 这些 IEEE 754 特殊值，也不允许 undefined。JavaScript 里 JSON.stringify(NaN) 会输出 null，就是为了保证结果符合规范。如果数据里确实有 NaN、Infinity（比如科学计算、机器学习结果），常见做法：一是转成 null；二是转成字符串 "NaN"、"Infinity"，前端解析时特殊处理；三是用一个约定的极大值代替 Infinity。JSON5 允许这些值，但发到普通 API 前必须处理。

Q.tsconfig.json 里能写注释，那我在项目的 .json 文件里也能写注释吗？

不能一概而论。tsconfig.json、VS Code 的 settings.json、部分 launch.json 之所以能有注释，是因为 TypeScript 工具链和 VS Code 使用 JSONC 解析器读取它们，这是特殊约定，不是 JSON 规范的一部分。如果你自己项目里的 config.json 被 JavaScript 的 JSON.parse、Python 的 json.loads、Java 的 Jackson 等标准库读取，注释会直接导致解析失败。想在配置文件里写注释，有几个选择：换成 JSONC 并用兼容的解析库（如 jsonc-parser）、换成 YAML/TOML、或者把注释放在文件外的 README 里。

Q.尾逗号（trailing comma）为什么在有些解析器里能过，在有些里不能过？

标准 JSON 严格禁止尾逗号：[1, 2, 3,] 或 {"a":1,} 都是非法的。但 JavaScript 语言允许尾逗号，所以 V8、SpiderMonkey 等 JS 引擎的宽松模式和 JSON5 都接受。Python 的 json 库、Java 的 Gson、Go 的 encoding/json 严格执行标准，遇到尾逗号直接报错。开发时你可能在浏览器控制台粘贴带尾逗号的 JSON 能解析，但发给后端就报错，就是这个原因。写标准 JSON 时删掉所有尾逗号，或者用格式化工具自动清理。

Q.JSON5 和 JSONC 到底该选哪个？

取决于用途。JSONC 更保守，只加了注释，其他语法基本和 JSON 一样，适合给现有 JSON 文件加人工说明（配置文件、示例数据）。JSON5 更激进，允许单引号、尾逗号、未加引号的 key、多行字符串、十六进制数字等，写起来接近 JavaScript 对象字面量，适合手写数据比较多、工具链自己控制的场景（Babel 配置、Rollup 配置）。如果你只需要注释支持，选 JSONC；如果你觉得双引号和引号 key 太啰嗦，选 JSON5。但两者都不能直接发给 API，必须转成标准 JSON。