排查接口报错的实用套路：用 JSON 格式化工具三步定位问题
接口返回一堆压缩过的 JSON、报错信息又语焉不详时，先别急着怀疑后端。这篇文章分享一套用格式化工具三步定位 JSON 问题的实用流程，附常见报错对照表和排查清单。
凌晨改完一个接口，联调时前端同学甩过来一句"返回的数据解析不了"，附带一坨挤在一行里的 JSON。这种场景大概每个写接口的人都遇到过——报错信息通常只有一句 Unexpected token，具体是哪个字段、第几行，全靠猜。
其实不用猜。把这段 JSON 丢进 JSON 格式化工具，摊开结构、跑一次验证，十几秒就能定位到具体位置。这篇文章整理了我们团队排查接口 JSON 问题时常用的三步流程，尽量少走弯路。
为什么压缩过的 JSON 很难一眼看出问题
生产环境返回的 JSON 大多是压缩过的，所有字段挤在一行，肉眼很难分辨括号有没有对齐、逗号是不是多了一个。再加上 JSON.parse 的报错信息往往只给一个字符位置，比如：
Uncaught SyntaxError: Unexpected token } in JSON at position 187
这个 position 187 是原始字符串里的偏移量，压缩成一行之后基本没法直接定位到"第几个字段"。
团队里流传一句话：多一个逗号、少一个引号，都能让你在深夜怀疑人生——但格式化一下通常十几秒就能找到问题。
三步排查法
我们常用的流程很简单：
- 先格式化，把结构摊开看
- 用验证功能拿到精确的报错位置
- 确认没问题后再压缩，附到工单或聊天记录里
第一步：格式化，把结构摊开看
把接口返回的原始字符串粘贴到输入框，点击格式化。工具会按缩进重新排列 JSON，同时做语法高亮，嵌套关系一下子就清楚了。比如下面这段被压掉换行的响应：
{"code":0,"data":{"userId":1024,"roles":["admin","editor"],"profile":{"nickname":"鸭鸭","avatar":"https://cdn.example.com/a.png",}}}
格式化之后能立刻看出 profile 对象结尾多了一个逗号——这也是最常见的 JSON 语法错误之一。所有处理都在浏览器本地完成，不会把接口数据上传到任何服务器，适合处理带敏感字段的响应体。
第二步：用验证功能精确定位报错位置
如果格式化按钮没反应或者提示出错，点一下验证，工具内部调用的正是 JSON.parse，会把浏览器原生抛出的报错原文展示出来，包括具体的字符位置。拿着这个位置，回到格式化后的文本里用编辑器的"跳转到字符"或者数一下缩进层级，基本能锁定到某一个字段。
第三步：压缩后再传给同事或存到工单里
问题定位并修复之后，别直接把格式化后的多行 JSON 贴到工单里——太占地方，而且很多工单系统会把换行吃掉导致再次变形。用压缩功能把它变回单行，复制粘贴、写日志或者存到数据库字段都更省心。
常见 JSON 报错对照表
下面是几种在联调时最常遇到的报错关键词，以及对应的排查方向：
| 报错关键词 | 常见原因 | 排查建议 |
|---|---|---|
Unexpected token } |
对象或数组结尾多了一个逗号 | 格式化后检查最后一个字段/元素后面是否多了 , |
Unexpected end of JSON input |
数据被截断，括号没有闭合 | 检查接口是否返回了完整响应，或前端是否做了分片拼接 |
Unexpected token ' |
用了单引号而不是双引号 | JSON 字符串必须用双引号，单引号在标准 JSON 里非法 |
Unexpected non-whitespace character |
JSON 后面还跟了多余内容 | 常见于日志里把 JSON 和一段文字拼在了一起，比如前面带了时间戳前缀 |
Unexpected token u |
把 undefined 当成合法值序列化进了 JSON |
检查后端序列化时是否有字段值是 undefined（应该是 null） |
排查前的自查清单
真正贴进格式化工具之前，可以先过一遍这份清单，很多问题肉眼就能揪出来：
- 字符串是否统一用双引号，而不是单引号或不加引号
- 对象和数组的最后一项后面有没有多余的逗号
- 花括号
{}和方括号[]是否成对，数量对得上 - 是不是混入了非 JSON 的内容（例如日志前缀、HTML 错误页）
- 数字字段有没有被前端不小心拼成了带引号的字符串
配合其他工具的小技巧
排查接口问题很少只用到一个工具。几个常见组合：
- 接口用了 JWT 鉴权时，先用 Base64 编解码 把 token 的 payload 部分解出来，再丢进格式化工具看里面的字段和过期时间。
- 怀疑是缓存返回了旧数据，可以用 Hash 生成器 对响应内容算一次哈希，对比两次请求是否真的返回了不同内容。
- 如果报错信息里出现了 URL 编码字符（比如
%7B%22code%22），先用 URL 编解码 还原成正常 JSON，再格式化。
这几个工具都是纯前端处理，数据不会离开浏览器，适合排查带有用户信息或鉴权字段的接口响应。
写在最后
大部分"JSON 解析失败"的问题，本质上都是一个逗号、一个引号或者一段多余字符引起的。比起对着压缩成一行的字符串数括号，先格式化摊开、再用验证功能拿到精确位置，通常是最快的路径。把这套三步流程和上面的对照表收藏起来，下次遇到深夜报警也能更从容一点。