JSON 校验失败的 10 个常见原因

把一段 JSON 贴进校验器却报语法错误，肉眼检查又找不到问题时，绝大多数情况都落在下面这 10 类里。JSON 的设计目标是与 JavaScript 对象字面量相似，但规范严格得多——它没有容错空间，任何一处不符合 RFC 8259 的写法都会导致整体解析失败。因此排查的关键不是「更仔细地看」，而是知道有哪些「看起来不像错的错」。

建议的排查顺序是：先用工具读出精确的行列位置（JSON 格式化与校验工具会直接定位到具体字符），再按下面清单从高频到低频逐一排除。

一、单引号代替双引号

JSON 只允许双引号。{'name': 'Tom'} 在 JavaScript 里完全合法，在 JSON 里必然失败。同理，键名必须加引号，{name: "Tom"} 也是非法的。这类问题在「从 JavaScript 代码里直接复制对象」时最常见，而 ' 与 " 的区别在长文本里极难用肉眼扫出。

二、尾随逗号

{"a": 1, "b": 2,} 最后一项之后多了一个逗号，JSON 不允许；数组同样如此：[1, 2, 3,]。这是手写配置文件最高频的错误，而且解析器给出的报错位置通常指向右花括号，容易误判成括号问题。

三、注释

JSON 标准没有任何注释语法，加 // 或 /* */ 都会被当成语法错误。需要注释时应改用 JSONC / JSON5 等扩展格式，或把说明写进专门字段（例如 "_comment": "..."）。把 .json 文件当 .jsonc 使用，是配置中心类项目的高频事故。

四、中文引号与全角符号

从 Word、微信、笔记软件里复制代码时，引号常被自动替换成弯引号（“ ” ‘ ’）或方引号（「」），它们看起来像引号，却不是 ASCII 字符。全角逗号（，）与全角冒号（：）同样不合法。这类错误的特点是「看着一模一样」，只能靠逐字符定位的工具发现，肉眼几乎不可靠。

五、undefined、NaN 与函数

{"a": undefined}、{"a": NaN}、{"a": () => 1} 都是 JavaScript 语法而非法 JSON。序列化前应先把 undefined 转为 null，把 NaN 与 Infinity 转为 null 或字符串，函数则根本不应出现在数据交换层。

六、数字格式越界

JSON 数字不允许前导零（01）、不允许小数点开头（.5）、不允许正号（+1）、不允许十六进制（0x1F）、不允许千分位分隔符（1,000）。更隐蔽的是精度问题：JSON 本身不限制数字范围，但 JavaScript 的 Number 是双精度浮点，超过 2 的 53 次方的整数会静默丢精度——雪花算法 ID、19 位订单号这类字段必须序列化为字符串。

七、转义与换行

字符串内部出现未转义的双引号或反斜杠会提前结束字符串。Windows 路径写在 JSON 里时，每个反斜杠都要写成两个。字符串内也不允许直接出现裸换行，应写成转义形式；正则表达式这类含大量反斜杠的内容是重灾区。

八、BOM 与不可见字符

Windows 记事本保存的 UTF-8 文件可能带 BOM，某些解析器会把它视为非法首字符；零宽空格、不间断空格也常随复制内容混入。用十六进制查看器检查文件开头几个字节，往往一眼就能定位。

九、结构不完整

括号、方括号数量不匹配，或粘贴时被截断（只复制了对象的前半段）。此时报错位置常在文件末尾，提示为「unexpected end of input」，属于特征明显的一类。

十、编码不是 UTF-8

接口返回 GBK 编码的中文，却被按 UTF-8 解析，会出现乱码甚至解析失败。HTTP 响应头、HTML meta 声明、文件实际编码三者不一致是常见根因，详见《字符编码与乱码排查：UTF-8、GBK、BOM》。

可执行的排查顺序

第一步：把内容粘进校验工具，读出精确行列位置，先处理报错的那一处；
第二步：修完立即重新校验——一处语法错误会让后续内容全部无法解析，报错通常只暴露第一个问题；
第三步：对「看着没问题」的内容做不可见字符检查（BOM、零宽字符、全角符号）；
第四步：语法通过但语义仍有误（如金额浮点误差、必填字段缺失）时，改用 JSON Schema 做结构校验与大数校验。

延伸阅读

需要直接验证内容时使用 JSON 格式化与校验工具；若正在纠结该用哪种配置文件格式，可继续阅读《JSON、YAML、TOML 怎么选》。