JSON 格式化报错的 5 个常见原因(附定位方法)

发布于 2026-05-23

报错的本质

JSON 标准(RFC 8259)严格到近乎死板。下面 5 种非常常见但 JSON 规范完全不允许的写法,会让解析器立刻报错:

1. 多余的尾逗号
2. 单引号代替双引号
3. 注释 // 或 /* */
4. 字段名没引号
5. 字符串里裸换行

下面逐个拆。

1. 多余的尾逗号(Trailing Comma)

最高频的错。对象的最后一个字段、数组的最后一项后面,不允许有逗号。

❌ 错误:

{
  "name": "张三",
  "age": 25,
}

报错:Unexpected token } in JSON at position 36(数字大概对应 } 的位置)。

✅ 正确:

{
  "name": "张三",
  "age": 25
}

为什么 JS 代码里能写但 JSON 不行? 因为 ES2017+ 才允许 JS 对象字面量带尾逗号,而 JSON 规范是 2017 之前的,跟不上语言演进。

定位方法:把整个 JSON 粘到在线 JSON 格式化,它会报出错位置(行号 + 列号),定位比浏览器 console 准。

2. 单引号

JSON 字符串必须用双引号,字段名也必须。Python / JS 习惯用单引号的人最容易踩。

❌ 错误:

{'name': 'zhangsan'}

✅ 正确:

{"name": "zhangsan"}

报错:Unexpected token ' in JSON at position 1

定位:报错位置直接指到单引号本身。

3. 注释 // 或 /* */

标准 JSON 不允许任何注释。这是 JSON 设计的故意选择(让数据保持纯净)。

❌ 错误:

{
  "host": "localhost", // 开发环境
  "port": 8080
}

如果配置文件需要注释,正确做法:

• 用 JSON5 或 JSONC(带注释的 JSON 超集),不是标准 JSON
• 或者用 YAML / TOML,这两种格式天然支持注释

转换可以走 YAML / JSON / TOML 互转。

4. 字段名没引号

JSON 要求字段名必须用双引号包起来,跟 JS 对象不一样。

❌ 错误:

{name: "zhangsan"}

✅ 正确:

{"name": "zhangsan"}

报错:Unexpected token n in JSON at position 1

容易混淆:JS 里 { name: 'x' } 是合法对象字面量,但它不是 JSON,只是 JS 对象。把它 console.log 出来再复制粘贴当 JSON 用就会报错。

5. 字符串里裸换行

JSON 字符串不允许直接换行,必须用 \n 转义。

❌ 错误:

{"msg": "第一行
第二行"}

✅ 正确:

{"msg": "第一行\n第二行"}

报错:Unexpected token \n in JSON at position ...

真实场景:从日志里复制一段多行字符串粘到 JSON 字段里,经常踩这个。

速查表

复杂结构怎么排查

对于 1000+ 行 JSON,光看报错位置不够。趁手 iKit 的 JSON 工具做了几件辅助:

1. 行内高亮报错位置:不只给字符索引,还会高亮报错行 + 上下文
2. 折叠层级:层层折叠定位深嵌套的错处
3. diff 模式:粘对比两份 JSON 看哪个字段差

如果是 jq / Python 报错呢?

命令行工具的报错也类似:

$ echo '{"a":1,}' | jq
parse error: Expected another key-value pair at line 1, column 8

>>> import json; json.loads('{"a":1,}')
JSONDecodeError: Expecting property name enclosed in double quotes: line 1 column 8 (char 7)

不管哪个工具,先看行 + 列号定位再改。盲改容易越改越错。

总结

JSON 报错 90% 是上面 5 种。养成习惯:报错先看位置,然后从那个位置往前找最近的可疑字符。打开在线 JSON 格式化粘进去也能立刻知道错在哪。