凌晨两点,接口挂了,日志里只有一行 Unexpected token < in JSON at position 0。这时候最没用的建议是「检查一下 JSON 格式」——你当然知道格式有问题,你要知道的是哪一行、第几个字符、该改什么。
JSON 的报错信息其实相当精确,只是没人教过怎么读。这一篇讲三件事:报错里的数字指哪里、七种几乎覆盖全部情况的原因,以及那些能过解析但会在后面坑你的写法。
先学会读那三个数字
现代浏览器的 JSON.parse 会给出 position,V8 还会补上 line 和 column。三者的含义是:
- position 是从字符串开头算起的字符偏移,从 0 开始。注意单位是 UTF-16 码元,一个汉字算一个,一个 emoji 算两个。中文密集的 JSON 里,position 和「人眼数的第几个字」经常对不上,差的就是 emoji。
- line 从 1 开始,column 也从 1 开始。列号按字符算,不是按字节,也不是按制表符展开后的位置。
- 报的位置是「解析器读到第一个不该出现的字符」的地方,不是错误的起点。少一个逗号时,报错往往落在下一个键的引号上;少一个右括号时,报错落在文件末尾。
所以看到 line 7, column 12,先看第 7 行第 12 个字符附近,然后往前看——真凶通常在同一行更靠前,或者上一行的行尾。
七个原因,覆盖九成情况
| 现象 | 真实原因 | 改法 |
|---|---|---|
Unexpected token < | 返回的是 HTML 错误页或登录页,不是 JSON | 先看响应头 Content-Type 与前 200 字节原文 |
Expected property name in double quotes | 用了单引号,或中文输入法的弯引号 | 键名与字符串统一用半角双引号 |
Unexpected token } | 尾逗号:最后一个元素后面多了一个逗号 | 删掉 ,} 或 ,] |
Unexpected token / | 写了注释 | JSON 不支持注释,删掉或改成字段 |
Unexpected token u / N | undefined、NaN、Infinity | 换成 null |
Unexpected number | 01、.5、+1、1. | 写成 1、0.5、1.0 |
Bad control character | 字符串里直接换了行,或反斜杠没转义 | 写成 \n、\\ |
一、返回的根本不是 JSON
position 0 配上 Unexpected token <,几乎总是同一个故事:网关返回了一个 HTML 错误页(502、登录跳转、WAF 拦截页),而你的代码直接对它调了 JSON.parse。也可能是接口被改成了返回 XML。position 0 的意思是「第一个字符就不对」,HTML 文档的第一个字符恰好是 <。
排查只需一步:在浏览器开发者工具的 Network 面板点开这个请求,看 Response 的原文,而不是看 Console 里打印出来的对象。Console 里那段被截断、被折叠的文本会误导你半小时。
二、单引号和中文引号
{'key': 1} 在 JavaScript 对象字面量里合法,在 JSON 里非法。写得多了,手会形成肌肉记忆。更隐蔽的是从 Word、公众号后台或聊天软件复制过来的文本里,引号是全角的「」或弯引号 “ ”,肉眼看几乎一样,JSON.parse 一读就崩。
检查办法:把整段粘进JSON 格式化工具,报错会指向具体位置;如果肉眼看着是双引号却一直报错,就把光标放到引号上左右移动一次,全角字符占两个字符位,移动时会露馅。
三、尾逗号
JavaScript 允许 [1, 2, 3, ],Python 允许,Go 甚至强制要求。JSON 不允许。这是跨语言手写配置时最高频的错误,报错信息是 Unexpected token }——它说的是「这里不该出现右括号」,因为解析器刚读完逗号,正等着下一个元素。
四、注释
JSON 没有注释。RFC 8259 明确只允许空白字符,而 // 和 /* */ 都不在其中。有人会引入 JSON5 或 JSONC(VS Code 的配置文件就是 JSONC),但那只在特定工具里有效,交给标准解析器一样报错。要在 JSON 里写说明,就加一个 "_comment" 字段,或者把说明放进文档。
五、undefined、NaN 和函数
从 JavaScript 里 JSON.stringify 出来的对象不会有这些,但手写或拼接字符串时经常出现。undefined 要换成 null;NaN、Infinity 在 JSON 里没有表示法,只能换成 null 或字符串 "NaN",然后在读取端自己处理。日期也一样:JSON 没有日期类型,只能写成 ISO 8601 字符串。
六、数字格式
JSON 的数字语法很窄:不允许前导零(01 非法,0.1 合法)、不允许正号、不允许小数点开头或结尾、不允许十六进制。从 Excel 或 CSV 拼出来的数据最容易带上前导零——工号 007 在 JSON 里必须是字符串 "007",当数字写就是语法错误。
七、字符串里的控制字符
字符串里直接按回车换行是非法的,必须写成 \n。Windows 路径 C:\Users\new 里的 \n 会被当成换行,\U 则是个非法转义,这两种情况都会报同一个错。路径要写成 C:\\Users\\new,或者统一换成正斜杠。
还有一个额外的:BOM。某些 Windows 工具保存的 UTF-8 文件开头带 EF BB BF 三个字节。文件本身没毛病,但字符串开头多了个不可见字符,JSON.parse 会在 position 0 报错。用文本编辑器存成「UTF-8 无 BOM」,或者在读取时先 replace(/^\uFEFF/, '')。
能过解析、但后面会坑你的写法
语法合法不等于数据正确。下面五种情况解析器一声不吭,问题留给三个月后的你:
- 重复键。
{"a": 1, "a": 2}合法,标准说行为由实现决定;浏览器和 Node 都取最后一个。上游多拼了一个字段,你永远不知道哪个生效。 - 大整数精度。超过 2 的 53 次方的整数(订单号、雪花 ID)在 JavaScript 里会被悄悄改写末几位。
9007199254740993读出来是9007199254740992。这类 ID 必须以字符串传递。 null与字段缺失。{"name": null}和{}在多数语言里映射到同一个结果,但语义不同:一个是「明确为空」,一个是「没有这个字段」。做部分更新(PATCH)时这两种会写出完全不同的行为。- 数字与字符串混用。
"1"和1在弱类型语言里换着用没事,到了强类型反序列化就整体失败,错误信息还只告诉你「字段类型不匹配」。 - 深度嵌套。几百层嵌套能让部分解析器栈溢出。这类结构通常说明数据建模出了问题,不该靠调大栈来解决。
一套能落地的定位流程
拿到报错之后按这个顺序走,通常三分钟内能定位:
- 看
position 0还是别的位置。是 0 就先怀疑「返回的不是 JSON」。 - 把原文(不是 Console 里打印的对象)粘进格式化工具,让它报出行号列号。
- 先点「压缩成一行」再点「格式化」:压缩能暴露出被换行掩盖的问题(字符串里的裸换行会被拼成一行,报错位置也随之改变)。
- 对着报错行往前找一行的行尾,看有没有漏逗号、多逗号。
- 确认引号是不是半角,字符串里有没有未转义的反斜杠。
- 修好之后,把这份 JSON 存成测试用例,别再让它回来第二次。
常见问题
为什么本地测试好的 JSON,线上就报错?
线上多了一层:网关、CDN、WAF、反向代理都可能改写响应体,或者在你出错时插入一段 HTML。还有一个常见原因是压缩:某些中间件会 gzip 之后忘记设置正确的 Content-Encoding,客户端解出来就是乱码。先比对原始字节,再怀疑 JSON 本身。
报错说 Unexpected end of JSON input,可我看着是完整的?
说明字符串被截断了:日志系统按长度截断、HTTP 响应没读完、或者复制时漏了最后几个字符。数一下括号是否配对——右括号比左括号少一个,就是这个原因。
JSON 里能写中文吗?
能。RFC 8259 要求使用 UTF-8,中文直接写没问题,\u4f60\u597d 这种转义写法也合法,两者解析结果一样。反倒要注意别用 GBK 保存文件——那就是上面说的乱码来源。中文参数进 URL 时的编码规则见URL 编码与 Base64。
把一段报错的 JSON 粘进JSON 格式化工具,行号列号会直接指到出问题的地方;想系统了解编码与转义的边界,读下一篇。
本文由 TextBench 团队撰写。最后更新:2026 年 11 月 19 日。