JSON 是大多数接口、配置文件和数据导出共同的语言,几乎每个开发者每天都在读写它。它看着简单,确实也简单,但一个逗号或引号放错,整条请求就解析不了。这篇指南讲清楚 JSON 的结构、怎么格式化与校验,以及那几种导致几乎所有 JSON 报错的小错误该如何修。
JSON 到底是什么
JSON 是 JavaScript Object Notation 的缩写,是一种存放结构化数据的文本格式。它只有几种基本积木,认全了整个格式就通了:
- 对象,用花括号,放键值对:
{ "name": "Ann", "age": 30 }。 - 数组,用方括号,放一列有序的值:
["red", "green", "blue"]。 - 字符串永远用双引号包起来:
"hello"。 - 数字不带引号:
42或9.5。 - 布尔值就是裸词
true和false。 - null 表示空值。
值可以自由嵌套,所以一个对象里能放数组,数组里又能放对象,想多深就多深。正是这种嵌套让 JSON 能描述几乎任何数据,也正是它让一份乱糟糟的 JSON 难以用肉眼读懂。
为什么要格式化
在网络上传输的 JSON 大多是压缩过的,也就是把空格和换行都去掉以省字节。这对机器很好,对人很痛苦。格式化(也叫美化)过的版本会加上一致的缩进和换行,让结构一眼可见。
对比一下。压缩版:
{ "user": { "id": 1, "name": "Ann", "roles": ["admin", "editor"], "active": true } }
格式化版:
{
"user": {
"id": 1,
"name": "Ann",
"roles": ["admin", "editor"],
"active": true
}
}
数据一样,但第二版立刻让你看清结构。把任意压缩 JSON 粘进格式化工具,就能拿回可读版本,而且一个值都不会改。
几乎能压垮所有 JSON 的错误
解析器拒收你的 JSON 时,几乎总是那一小撮错误之一。下面逐个讲,并给出修法。
末尾多余的逗号
JSON 不允许对象或数组最后一项后面还有逗号,尽管 JavaScript 允许。这是最常见的错。
{
"a": 1,
"b": 2,
}
2 后面那个逗号是非法的。删掉它。校验器会直接指到那一行。
用了单引号而不是双引号
JSON 的字符串和键必须用双引号。单引号在 JavaScript 里合法,在 JSON 里不行。
{ 'name': 'Ann' }
键和值都要换成双引号:{ "name": "Ann" }。
没加引号的键
对象的键永远是带引号的字符串。{ name: "Ann" } 是 JavaScript 对象字面量,不是 JSON。把键包起来:{ "name": "Ann" }。
项之间缺逗号或多逗号
对象里每个键值对、数组里每个元素之间正好用一个逗号分隔,最后一项后面不加。两个键值对之间漏了逗号,或者逗号写重了,都会失败。
字符串里没转义的字符
如果字符串里含双引号或反斜杠,必须用反斜杠转义。字符串里直接换行也是非法的,要用 \n。
{ "quote": "She said \"hi\"", "path": "C:\\Users\\Ann" }
注释
JSON 没有注释。以 // 开头或用 /* */ 包起来的行都会失败。如果配置文件里确实需要注释,可以看看 JSON5 或 JSONC,它们是允许注释的超集,但纯 JSON 不行。
怎么校验 JSON
校验回答一个问题:这段文本是不是合法 JSON,不是的话问题在哪。一个好的校验器做三件事:告诉你通过还是失败,指出第一个错误的行列位置,并说明它期望的是什么。最后一点最有用。像「期望一个逗号或右花括号」这样的提示,通常就直接告诉你少了什么。
最快的流程是:粘进 JSON,读第一个错误,修那一行,再校验。错误常会连锁,所以解析器可能报在真正错误之后很远的位置。永远先修最靠前的错误,再校验一遍,然后再去追后面的。
格式化、压缩与转换
三种操作覆盖日常大部分 JSON 工作:
- 格式化把压缩 JSON 变成带缩进、可读的排版。两个空格是常见默认,有些团队偏好四个。选一种并保持一致。
- 压缩反过来,去掉空白生成最小负载。用在你发出或存储的内容上,而不是给你看的内容上。
- 转换把 JSON 与其他格式互转。JSON 转 CSV 方便用表格打开,JSON 转带类型的结构(TypeScript 接口、Go 结构体)能省去手写类型。
浏览器端工具在本地完成这一切,当 JSON 含敏感内容时这一点很重要。仅仅为了加点缩进,不该让数据离开你的机器。
处理深层嵌套的 JSON
大型接口响应可能嵌套很多层,格式化在这里回报最大。几个习惯有帮助:
- 折叠与展开。 读一份 500 行的响应,如果能折起你不关心的分支、只展开你在追的那条路径,会轻松得多。
- 按键搜索。 知道字段名时,搜索能直接跳过去,不用滚动。
- 盯住括号。 手写 JSON 的大多数错误来自开了却没闭的花括号或方括号。格式化让它们竖向对齐,少了哪个一目了然。
一份快速清单
在你把 JSON 发出去、或粘到必须解析它的地方之前,过一遍:
- 每个键和字符串都用双引号。
- 任何对象或数组的最后一项后没有多余逗号。
- 项之间正好一个逗号,没有遗漏。
- 字符串里的特殊字符已转义。
- 没有注释。
- 花括号和方括号成对闭合。
丢进校验器,工具一遍就替你确认这些。
常见问题
为什么我的 JSON 在 JavaScript 里能用,却解析失败? JavaScript 对象字面量比 JSON 宽松。它允许单引号、不带引号的键、末尾逗号和注释,这些 JSON 都不允许。修法是把文本收紧成严格的 JSON。
键的顺序有保证吗? JSON 本身不保证键序,你也不该依赖它。如果顺序重要,用数组,数组按定义就是有序的。
JSON 文件能多大? 格式本身没有上限,但解析器和编辑器在超大文件上会变慢。几 MB 的数据更适合流式处理或拆分,而不是整个加载进一个视图。
JSON 能存日期吗? 不能作为原生类型存。日期以字符串保存,通常用 ISO 8601 形式如 2026-01-31T10:00:00Z,再由你的代码去解析。
格式化、校验、先修第一个错误,JSON 就不再是神秘故障的来源,而回到它本该是的样子:简单、可预测。