快乐时光

Unexpected token 到底在第几行?JSON 报错定位的笨办法最有效

约 4 分钟

JSON 解析器只告诉你「第 N 个字符附近有问题」,而这个 N 常常指向逗号之后。这篇讲清 position 与行列号的换算,以及尾逗号、单引号、注释、BOM 这四类占九成的原因。

报错位置为什么总是「差一点」

解析器是逐字符读的,遇到它不认识的东西才报错。多写一个逗号的时候,它在遇到逗号时并不认为是错——它期待的是下一个键,直到读到 } 才发现「这里不该出现 }」。所以报错位置往往指向错误的下一个字符,而不是错误本身。

实用推论:看到 "Unexpected token }" 时,先把光标放到报错位置往前一格,检查是不是多了个逗号;看到 "Unexpected token '" 则检查引号类型;看到 "Unexpected end of JSON input" 通常是括号没闭合。

把 position 换算成行列

position 是「从字符串开头数第几个字符」,包含换行。要定位到人看得懂的行号,需要数到那个位置为止出现过多少个换行符。手数不现实,格式化工具会直接做这件事——它一边扫描一边维护行号,并且能把出错的那一行高亮出来。

自己写脚本时注意一个坑:很多运行时报告的 offset 是按 UTF-16 码元算的,含中文的 JSON 里一个汉字算 1 个码元但显示宽度是 2,直接拿去切字符串会切错位置。要按码元切,不要按显示字符切。

四类原因占了九成

按出现频率从高到低:

  • 尾逗号:{"a":1,} 在 JavaScript 里合法,在 JSON 里非法。手写配置、手改接口返回值时最常见。
  • 单引号:JSON 只认双引号。从 JS 对象、Python dict 直接拷过来时必踩。
  • 注释:JSON 标准里没有注释,// 和 /* */ 都会被当成非法字符。需要注释就用 JSON5 或 JSONC,别硬塞进 JSON。
  • BOM:Windows 记事本保存 UTF-8 时会加三个字节的 BOM(EF BB BF),解析器把它当成第一个字符,于是报「Unexpected token」而位置是 1。这是最隐蔽的一种。

还有三类不常见但会咬人的

NaN 和 Infinity:JSON 规范只有数字字面量,NaN、Infinity、undefined 都不是合法值。JavaScript 的 JSON.stringify 会把它们变成 null,但手写的文件里出现就直接报错。

数字格式:前导零(01)、前导加号(+1)、小数点结尾(1.)在 JSON 里都不合法。从 Excel 或 CSV 拼出来的数据很容易带上这些。

不可见字符:从网页复制 JSON 时偶尔会带上零宽空格(U+200B)或不换行空格(U+00A0),肉眼完全看不出来,解析器的报错又指向一个「看起来完全正常」的位置。遇到「明明没问题却报错」,先把内容粘到能看到不可见字符的编辑器里检查一遍。

大文件不要靠眼睛

几十 KB 以上的 JSON,肉眼找错基本没有胜算。可行的流程是:先整体格式化,让结构展开;如果格式化本身失败,就从报错位置附近往后找最近的括号不匹配;再不行就用二分法——删掉后半段看是否还报错,把问题区间缩到一小段。

另外提醒一句:格式化一个有几百 MB 的 JSON 会让浏览器标签页直接卡死,这类文件应该用命令行工具(jq、Node 脚本)处理,不要放进网页工具。

常见问题

为什么 JSON 不允许注释?
历史原因:JSON 是从 JavaScript 的对象字面量语法里抽出来的最小子集,道格拉斯·克罗克福德刻意不包含注释和尾逗号。注释会让「同一份数据有两种读法」,也会让机器生成与人工维护的配置文件混在一起时难以判断。需要注释就换 JSON5 / JSONC / YAML,或者约定用 "_comment" 字段。
报错说 position 1,但第一个字符看起来完全正常?
九成是 BOM。用十六进制查看器打开文件,如果开头是 EF BB BF,那就是它。解决办法是用「UTF-8 无 BOM」重新保存,或者用脚本 strip 掉开头这三个字节。
格式化之后键的顺序变了,有影响吗?
按规范,JSON 对象是无序的键值集合,顺序不承载语义,任何依赖顺序的做法都不安全。但现实中有些系统确实依赖插入顺序(尤其是用 JS 解析后直接遍历的场合),所以格式化工具一般会保留原始顺序,只调整缩进和换行。

接着读

Unexpected token 到底在第几行?JSON 报错定位的笨办法最有效 · 快乐时光