JSON 格式化与前端调试：报错对照与排查顺序

调试接口时，控制台抛出 Unexpected token } in JSON，你盯着屏幕上 200 行压缩成一团的 JSON 找了十分钟，最后发现是第三个字段后面多了一个逗号。这种经历几乎是每个前端和测试的必修课。JSON 的语法规则其实非常少，报错类型也就那几种，摸清之后，90% 的问题可以在 30 秒内定位。这篇指南把规则、报错和排查顺序整理成一张速查手册。

一、先背下 JSON 的五条硬性规则

• 键必须用双引号：{name: "张三"} 不合法，必须是 {"name": "张三"}。单引号也一样不合法；
• 不允许尾逗号：最后一个成员后面的逗号必须删掉，这是「Unexpected token }」的头号来源；
• 不允许注释：// 备注 或 /* */ 在标准 JSON 里都是非法的（JSON5/JSONC 扩展才支持）；
• 字符串必须双引号包裹，且内部换行要写成 \n，不能直接敲回车；
• 数值、布尔、null 不加引号：{"age": "18"} 和 {"age": 18} 是两回事，前者是字符串，做数值比较会踩坑。

还有一类高频雷区肉眼看不出来：中文引号。从聊天记录、Word 文档复制 JSON 时，双引号 " 常被自动替换成中文引号 “ ”，肉眼几乎无法分辨，但解析器立刻报错。遇到「明明看起来没错」的 JSON，先检查引号是不是半角的。

二、五种高频报错的排查对照表

报错信息	典型原因	排查动作
Unexpected token } or ]	尾逗号、缺成员	检查最后两个成员之间与末尾的逗号
Unexpected token '	单引号或中文引号	全文替换为半角双引号
Unexpected end of JSON input	内容被截断，括号不闭合	从末尾往前数括号是否配对
Unexpected token N / U	写了 NaN、undefined、None	换成 null
Unexpected number	数值里混入了非法字符，如 0x 开头、千分位逗号	检查数值字面量格式

把报错粘贴进JSON 格式化工具，多数情况下工具会直接指出出错的行列号，比在编辑器里数括号快得多。

三、接口调试的标准三步

1. 格式化：把接口返回的压缩 JSON（一行长串）粘贴进工具格式化，先肉眼确认结构：数据在 data 字段还是 result 字段，数组在哪一层；
2. 校验：格式化成功本身就等于一次语法校验。如果接口返回的「JSON」格式化失败，说明后端输出有问题（比如错误页返回了 HTML），这往往不是你代码的锅；
3. 对比：接口行为变了？把上一次正常的返回和这一次的返回分别格式化后对比字段，缺字段、类型变化（数字变字符串）一眼可见。配合 JSON Diff 类工具可以逐字段自动对比。

四、格式化背后的两个小知识

格式化不改变数据。JSON 的「格式」只是空白字符的排布，解析后完全等价。所以压缩（去掉空白）可以减小传输体积——生产环境的接口返回通常都是压缩过的，一行 50KB；而格式化只是给人看的调试手段，不要把格式化后的 JSON 当成「新数据」存回后端。

键的顺序没有语义。标准 JSON 里 {"a":1,"b":2} 和 {"b":2,"a":1} 完全等价。如果你在对比两段 JSON 时发现「只是顺序不同」，可以直接判定相等，不必逐字段再核。

常见问题

问：JSON 里的日期怎么存？
JSON 没有日期类型。惯例是存 ISO 8601 字符串（"2026-01-15T09:30:00+08:00"）或 Unix 时间戳（毫秒），团队内部统一一种即可，混用最容易出时区 bug。

问：大数据量的 JSON 格式化会卡吗？
浏览器端格式化几 MB 的 JSON 没有问题；超过 20MB 建议先用命令行工具（如 jq）处理，或截取问题字段单独格式化。

问：粘贴的 JSON 会泄露数据吗？
取决于工具实现。我们的JSON 格式化在浏览器本地完成解析和渲染，数据不经过服务器；处理含用户信息的接口返回时，建议优先用本地工具。