JSON 格式错误怎么排查？常见语法错误与修复方法

先定位：报错行列怎么读，为什么常常指偏

排查 JSON 错误的第一步是拿到准确的行列位置，第二步是明白这个位置的含义：它是解析器「发现不对劲」的地方，不一定是你写错的地方。

一句话定义：JSON 语法校验，是按 JSON 规范逐字符解析文本，在第一个不符合语法的位置停下并报出行列——它只判断格式合不合法，不判断数据对不对。

错误位置为什么会指到下一行

解析器是顺序读取的。假设你在某个键值对后面漏了一个逗号，解析器读完这个值之后期待逗号或收尾括号，结果读到了下一个键名的引号——此时它才知道出错，报的位置就落在下一行。所以正确的检查方式是：以报错位置为终点，向前检查最近一个完整的语法单元是否收尾正常。

用美化模式反过来定位

有个实用技巧：把可疑内容分段粘贴校验。如果一大段 JSON 报错但看不出问题，把它拆成几块分别校验，能快速缩小范围。校验通过后再用美化模式重排缩进，结构不对的地方会在缩进层级上直接暴露出来——本该平级的两个字段缩进不一致，通常意味着括号配对出了问题。

先确认是不是一段完整的 JSON

还有一类常见情况是内容本身就不完整：从日志里复制报文时被截断了，或者拿到的其实是多行 JSON（每行一个独立对象的那种格式），整段当成一个 JSON 解析当然失败。后者需要逐行处理，而不是修语法。

五种高频语法错误与逐个修法

实际遇到的 JSON 解析失败，绝大多数是下面五种之一。按这个顺序排查，效率最高。

尾随逗号：手感带来的错误

JavaScript 允许数组和对象字面量的最后一项后面留逗号，很多编辑器还会自动补上，但 JSON 规范不允许。手写或手动删改 JSON 时特别容易留下——删掉最后一个字段，前一个字段后面的逗号就成了尾逗号。

单引号与无引号键：从代码里复制的后遗症

直接从 JS 代码里复制一个对象字面量当 JSON 用，通常同时踩中这两条：键没加引号、字符串用单引号。这两种写法在 JS 里完全合法，作为 JSON 一律不行。JSON 要求所有键和所有字符串值都用双引号。

中文引号：最难用肉眼发现的一类

在中文输入法下打引号，得到的是排版用的成对弯引号，和 JSON 要求的直双引号是不同的字符，但在多数字体下几乎看不出区别。同类的还有全角冒号和全角逗号。如果报错位置附近的语法「看起来完全正确」，优先怀疑这一类。批量处理可以先用 全角半角转换 或 中英标点转换 把全角标点统一成半角。

字符串内换行：必须转义

JSON 字符串必须写在一行内，内部的换行要写成 \n。把一段多行文本（比如一段日志、一封邮件正文）塞进 JSON 字段时最容易出这个问题。手动加转义容易漏，可以用格式化页面的转义功能，把整段文本一次性转成合法的 JSON 字符串体；反过来也能把转义后的字符串还原成可读文本。

JSON 不是 JavaScript：那些看着合法其实不合法的写法

JSON 的语法源自 JavaScript 的一个子集，但它是一个独立的、更严格的规范。凡是「在 JS 里能跑」的直觉，用在 JSON 上都需要重新确认。

注释、undefined 与特殊数值

标准 JSON 不支持任何注释。undefined 不是合法的 JSON 值；NaN 和 Infinity 同样不合法，尽管它们在 JS 里是有效的数值。序列化含这些值的数据时，需要先决定用 null 还是字符串来表示它们，不能指望解析器认。

数字写法的限制

JSON 的数字不允许前导正号（+1 不合法），不允许多余的前导零（01 不合法），不允许十六进制写法，小数点前后都必须有数字（.5 和 5. 都不合法）。这些在 JS 里大多能接受，写 JSON 时得改成规范形式。

顶层值与空白

现行规范允许顶层是任意合法的 JSON 值，不一定非得是对象或数组——单独一个数字、一个字符串、一个 true 都是合法的 JSON 文档。反过来，文档末尾除了空白之外不能有任何多余内容，两个 JSON 对象直接首尾相连不是合法 JSON。

不报错但结果是错的：大整数、重复键与编码

比语法错误更麻烦的是校验通过、数据却已经不对了。这几类问题不会有任何提示，只能靠事先知道。

大整数精度丢失

JSON 数字在多数语言里被读成双精度浮点数，能精确表示的整数有上限。超过这个范围的长整数——雪花 ID、订单号、某些平台的用户 ID——解析后末尾几位会被舍入，而且不报任何错。这类标识符在设计接口时就应该用字符串传输。

本站的格式化页面对这类问题做了两件事：检测到超出安全范围的数字时给出提示；重排输出时原样保留数字的原始写法，不经过「解析成数值再输出」的过程，所以格式化本身不会改掉你的数字。这一点值得注意——不少格式化工具会在美化过程中悄悄改写数字。

重复键：后面的会覆盖前面的

同一个对象里出现两个相同的键，JSON 规范没有明确禁止，多数解析器的行为是后者覆盖前者，不报错。手动拼接或多份配置合并时容易出现，表现为「明明设置了却不生效」。排查时用格式化页面的键排序功能重排一遍，重复的键会相邻显示，比在原文里逐个找容易得多。

编码与字节序标记

JSON 文本应当使用 UTF-8。从某些编辑器保存的文件开头会带一个字节序标记，它不可见，但会让严格的解析器在第一个字符就报错——报错位置指向第 1 行第 1 列，而你看到的第一个字符明明是正常的花括号。遇到这种「第一个字符就报错但看着没问题」的情况，先怀疑文件开头有隐形字符，用 富文本清理 过一遍即可。

校验通过之后：转成表格与其他格式

JSON 校验通过只说明格式合法，接下来通常还要把它变成能用的形态——给人看的表格，或者别的系统要的格式。

转成表格：嵌套结构要先想清楚怎么摊平

JSON 转 CSV 能把对象数组转成表格。难点在嵌套：一个字段的值本身是对象或数组时，需要决定是摊平成多列（用点号连接层级作为列名）还是整体塞进一个单元格。行数不定的嵌套数组没有无损的表格表示，转换时必然要做取舍，这一点在动手前就该想清楚，否则容易得到一张看着有数据、实际没法用的表。

从表格生成 JSON：注意类型

CSV 转 JSON 的反方向问题是类型判断：CSV 里一切都是文本，转成 JSON 时 007 该是数字 7 还是字符串 "007"，true 该是布尔还是字符串。编号、手机号、邮政编码这类前导零有意义的字段，必须按字符串处理，否则前导零会全部丢失。

压缩与美化各用在什么时候

美化模式加缩进和换行，给人读、做代码审查、贴进文档时用。压缩模式去掉所有非必要空白，传输和存储时用——对大报文来说体积差别相当可观。两者信息完全等价，可以随时互转，不影响数据本身。需要对比两份 JSON 的差异时，先把两边都美化成同样的缩进再用 文本对比，比直接对比压缩后的单行内容清楚得多。

常见问题

JSON 报 Unexpected token 是什么意思

意思是解析器在某个位置读到了一个当前语法状态下不该出现的字符。它指出的位置是「发现问题的地方」，而不一定是「写错的地方」——比如少写一个逗号，解析器要读到下一个键名才发现不对，报的位置就在下一行。所以看到报错先别盯着那一行改，往前检查上一个完整的键值对是否收尾正常。

JSON 里能写注释吗

标准 JSON 不支持任何形式的注释，双斜线和斜杠星号都会直接导致解析失败。这是 JSON 作为数据交换格式的有意取舍。如果确实需要注释，常见变通是加一个专门的说明字段（比如 _comment），或者改用支持注释的配置格式如 YAML。有些工具支持所谓的 JSONC（带注释的 JSON），但那是各自的扩展，把它交给标准解析器一样会报错。

为什么最后一项后面多一个逗号就报错

因为 JSON 规范不允许尾随逗号。JavaScript 从 ES5 起在数组和对象字面量里允许尾逗号，很多人的手感是从写代码带过来的，但 JSON 没跟这个变化。表现是数组最后一个元素或对象最后一个键值对后面多了个逗号，解析器接着期待下一个值，却读到了收尾的括号。修法就是把那个逗号删掉——用格式化工具的美化模式重排一遍，这类问题也会一并暴露出来。

JSON 的键和字符串必须用双引号吗

必须。JSON 里所有的键都要用双引号包起来，所有字符串值也必须用双引号，单引号一律不合法。这是和 JavaScript 对象字面量差别最大的一点——JS 里 {name: '张三'} 完全合法，作为 JSON 则两处都错。从代码里复制对象字面量当 JSON 用，几乎必然踩这个坑。

看着引号都对，为什么还是解析失败

大概率是中文输入法打出的弯引号。中文状态下输入的成对引号是排版用的全角引号，和 JSON 要求的直双引号是完全不同的字符，但在很多字体下长得非常像，肉眼几乎分辨不出。同类问题还有全角冒号和全角逗号。判断方法是把可疑片段单独放大看，或者干脆用查找替换把全角标点批量换成半角，再重新校验。

JSON 字符串里怎么写换行

写成 \n 转义，不能直接按回车。JSON 规范要求字符串必须写在一行内，字符串里的实际换行符必须转义。同样需要转义的还有双引号、反斜杠、制表符。如果你是从一段多行文本生成 JSON，用格式化页面的转义功能把整段文本转成合法的 JSON 字符串体，比手动加反斜杠可靠得多。

很长的数字解析后末尾变成 0 了是怎么回事

这是精度丢失，不是解析错误。JSON 里的数字在多数语言中会被读成双精度浮点数，能精确表示的整数有上限，超过之后末尾几位会被舍入。典型场景是后端返回的雪花 ID、订单号这类十几二十位的长整数，前端拿到就变了。规范的做法是这类标识符在传输时用字符串表示。本站格式化页面在检测到超出安全范围的数字时会给出提示，并且重排输出时原样保留数字的原始写法，不会把它改掉。

这个校验工具会把我的数据上传吗

不会。JSON 格式化与校验完全在浏览器本地完成，内容不上传、不写入任何服务器。含接口密钥、用户数据的调试报文可以直接粘进去排查；不过更稳妥的做法始终是——粘之前先把明显的敏感字段值换成占位符，任何在线工具都一样。