如何修复常见 JSON 错误：开发者生存指南

Source: Dev.to

请提供您希望翻译的具体文本内容，我将为您翻译成简体中文。

介绍

你是否曾经熬夜，盯着一条只写着 “Unexpected token” 的红色错误信息？JSON（JavaScript 对象表示法）是数据交换的通用语言，但即使是多余的逗号或错误的引号类型也会导致一切崩溃。如果你想快速进行一次合理性检查，在开始调试之前先把你的负载通过 JSON 格式化工具处理一下。

在本指南中，我将拆解多年里我见过的最常见的 JSON 错误，精准展示如何识别它们，并提供可立即应用的实用修复方案。无论你是刚开始使用 API，还是已经集成服务多年，懂得阅读并纠正这些错误都能为你省去大量的挫败感。

1. 尾随逗号

问题 – 在对象或数组的最后一个项目后面留下逗号。与 JavaScript 不同，JSON 不容忍尾随逗号，解析器会抛出类似 “Unexpected token ‘}’” 的错误。

无效的 JSON（尾随逗号）

{
  "name": "John Doe",
  "age": 30,
  "city": "New York",
}

修复

删除最后的逗号。

{
  "name": "John Doe",
  "age": 30,
  "city": "New York"
}

如何避免

• 使用集成到编辑器中的 JSON 验证器或 linter；许多工具会自动高亮尾随逗号。
• 配置你的格式化工具（Prettier、ESLint 等）在保存时移除尾随逗号。
• 当从 JavaScript 复制对象时，在将其用于配置文件或 API 调用之前，先通过验证器（例如 CodeItBro 的 JSON 验证器）进行检查。

2. 错误的引号字符

问题 – JSON 要求 双引号 用于所有字符串和属性名。单引号在 JavaScript 中合法，但在 JSON 中会导致 “unexpected character” 错误。

无效的 JSON（单引号）

{
  'name': 'John Doe',
  'active': true
}

修复

将所有单引号替换为双引号。

{
  "name": "John Doe",
  "active": true
}

为什么这很重要

• 使用一致的双引号可确保你的 JSON 在各种语言和平台上都是有效的。
• 避免不同解析器对单引号的不同解释导致的细微错误。

3. 未加引号的属性名

问题 – 在 JavaScript 对象字面量中可以省略键的引号，但 JSON 永不允许这样做。

无效的 JSON（未加引号的键）

{
  name: "John Doe",
  age: 30
}

修复

为每个属性名加上双引号。

{
  "name": "John Doe",
  "age": 30
}

提示

• 现代编辑器在启用 JSON 语法模式时通常会高亮未加引号的键。
• 开启 JSON 代码检查（lint）可以及早捕获此类错误。

4. 项目之间缺少逗号

Problem – 忘记在属性（或数组元素）之间添加逗号会导致错误，例如 “Unexpected string”。

Invalid JSON (missing comma)

{
  "firstName": "John"
  "lastName": "Doe"
}

Fix

添加缺失的逗号。

{
  "firstName": "John",
  "lastName": "Doe"
}

Quick check

当错误指向看起来没有问题的行时，请检查 前一行 是否缺少逗号。

5. 括号不匹配

问题 – 每个 { 必须有对应的 }，每个 [ 必须有对应的 ]。在较长或深度嵌套的 JSON 中，容易忽视缺少的闭合括号，导致 “Unexpected end of JSON input”。

无效的 JSON（缺少闭合大括号）

{
  "users": [
    {"name": "Alice"},
    {"name": "Bob"}
  ],
  "total": 2

修复

{
  "users": [
    {"name": "Alice"},
    {"name": "Bob"}
  ],
  "total": 2
}

提示

• 大多数编辑器会高亮匹配的括号。
• 使用 JSON 格式化工具/美化器来缩进嵌套层级；不匹配的括号会变得明显。

6. 无效的数字格式

问题 – JSON 只支持标准十进制数字。前导零、十六进制表示以及 NaN、Infinity 等特殊值都是非法的。

无效的 JSON（错误的数字）

{
  "quantity": 007,
  "price": 0xFF,
  "discount": NaN
}

修正

使用正确的十进制数字；将不受支持的值替换为 null（或有效的数字）。

{
  "quantity": 7,
  "price": 255,
  "discount": null
}

注意

科学计数法（例如 1.5e10）是有效的 JSON。

7. 不支持的数据类型

问题 – JSON 仅限于六种数据类型：string, number, boolean, null, array, object。诸如 undefined、函数、Date 对象、正则表达式和注释等值不被允许。

无效的 JSON（不支持的类型）

{
  "name": "John",
  "age": undefined,
  "callback": function() { return true; },
  "created": new Date()
}

修复

转换或删除不支持的值。

{
  "name": "John",
  "age": null,
  "callback": null,
  "created": "2025-01-30T10:30:00Z"
}

转换检查清单

• 将 undefined 替换为 null。
• 将函数转换为字符串或删除它们。
• 将日期表示为 ISO‑8601 字符串。
• 将正则表达式转为普通字符串。
• 对自定义对象使用 toJSON() 进行序列化。

8. JSON 中的注释

问题 – JSON 不允许注释。添加 /* … */ 或 // 会导致解析器拒绝该文件。

含有注释的无效 JSON

{
  "name": "John Doe",

  /* Age in years */
  "age": 30
}

包含说明的选项

1. 添加专用的注释字段（例如 _comment），其值为字符串。
2. 将文档单独保存（README、docs 文件夹等）。
3. 仅在你的工具明确支持时使用 JSONC（带注释的 JSON）。

9. 字符串中的转义序列

JSON 中的字符串可以包含转义序列（例如 \n、\t、\\、\"）。
确保所有反斜杠都已正确转义；否则解析器会将其视为无效字符。

最后提示

• 尽早验证 – 在提交之前，对每个 JSON 负载使用验证器或 linter 进行检查。
• 启用编辑器支持 – 大多数现代 IDE 都内置了 JSON 语法高亮、括号匹配和 lint 功能。
• 自动化格式化 – 配置格式化工具（如 Prettier、jq 等）在保存时或作为 CI 流程的一部分运行。

只要牢记这些常见陷阱，你就能大幅减少追踪神秘的 “Unexpected token” 错误的时间，投入更多精力构建出色的应用。祝编码愉快！

常见 JSON 错误及解决方法

在使用 JSON 时，一个小小的拼写错误就可能导致数小时的调试。下面列出了一些最常见的陷阱、出现原因以及避免或解决它们的实用方法。

1. 无效的转义序列

JSON 字符串只允许特定的转义序列（例如 \n 表示换行，\t 表示制表符，Unicode 转义如 \u00A9）。任何未被识别的转义都会触发解析错误。

包含错误转义序列的无效 JSON

{
  "path": "C:\\new\\folder",
  "message": "Line 1\\xLine 2"
}

使用正确转义的有效 JSON

{
  "path": "C\\\\new\\\\folder",
  "message": "Line 1\\nLine 2"
}

提示： 随手准备一份有效转义序列的列表，或依赖编辑器的语法高亮来发现无效的转义。

2. 重复的属性名

虽然某些解析器容忍重复键，但 JSON 规范 并未 定义应如何处理它们。不同实现可能保留第一个值、最后一个值，或直接抛出错误，导致结果不可预测。

含有重复键的有问题的 JSON

{
  "name": "John Doe",
  "age": 30,
  "name": "Jane Doe"
}

已纠正的 JSON —— 每个键仅出现一次

{
  "firstName": "John",
  "lastName": "Doe",
  "age": 30
}

建议： 使用有意义且唯一的属性名，以确保跨平台的数据保持可预测。

3. 调试大型 JSON 文件

当 JSON 文件很大且错误不明显时，系统化的排查方法可以为你节省大量时间。

技巧

• 使用 JSON 校验器 —— 在线工具会高亮错误并显示行号。
• 先格式化文件 —— 合适的缩进可以暴露结构性问题，如括号不匹配。
• 二分搜索你的 JSON —— 注释掉（或暂时删除）一半内容，验证剩余部分，重复此过程直至定位问题。
• 检查编码 —— 确保文件为 UTF‑8；隐藏的 BOM 或特殊字符可能导致难以理解的错误。
• 以编程方式验证 —— 将解析包装在 try/catch 块中，并记录错误信息和位置。

4. 防止错误 – 最佳实践

结束语

正确使用 JSON 并不光鲜亮丽，但却至关重要。只要记住核心规则——没有尾随逗号、字符串和键必须使用双引号、数字格式正确、转义序列有效、且键不能重复——就能在代码进入生产环境前消除大多数语法错误。当问题出现时，系统化的调试和优秀的工具能够帮助你快速定位并修复它们。

你最近遇到过这些错误吗？
哪些工具或技巧帮你化解了危机？在评论中分享你的经历，让我们互相帮助，避免深夜的 JSON 头疼。

如果你觉得本指南有帮助，收藏它或分享给你的团队。祝编码愉快！