解决 "Unexpected token in JSON" 及常见的 JSON 解析错误：完整指南

JSON (JavaScript Object Notation) 是现代 Web 通信的基石。无论您是在构建 REST API、配置服务器还是存储应用状态，JSON 无处不在。然而，它严格的语法经常导致令人沮丧的错误，如 SyntaxError: Unexpected token、JSON.parse: unexpected character 或简单的 invalid JSON format。

在本指南中，我们将分解最常见的 JSON 解析错误，解释它们发生的原因，并向您展示具体如何修复它们。

1. 常见的 JSON 错误消息

当解析器（如 JavaScript 中的 JSON.parse()）遇到无效的 JSON 时，它会抛出错误。根据环境的不同，您可能会看到：

• 浏览器 (Chrome/V8): SyntaxError: Unexpected token ' in JSON at position 0
• Firefox: SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data
• Node.js: SyntaxError: Unexpected token ... in JSON at position ...
• Python: json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes

关键信息通常是解析器不预期的字符以及它发生的位置（或行/列）。

---

2. 核心原因与解决方案

2.1 使用单引号而不是双引号

JSON 严格要求键和字符串值都必须使用双引号 (")。单引号 (') 在 JavaScript 对象中是有效的，但在 JSON 字符串中是无效的。

错误示例:

{
  'name': 'Tool3M'
}

解决方案: 将所有单引号替换为双引号。

{
  "name": "Tool3M"
}

2.2 尾随逗号 (Trailing Commas)

与现代 JavaScript 不同，JSON 不允许在对象或数组的最后一个项目之后出现逗号。

错误示例:

{
  "id": 1,
  "status": "active",
}

解决方案: 删除最后一个属性后的逗号。

{
  "id": 1,
  "status": "active"
}

2.3 键未加引号

在 JSON 中，键必须始终是包裹在双引号中的字符串。

错误示例:

{
  id: 123
}

解决方案: 为键加上双引号。

{
  "id": 123
}

2.4 JSON 中的注释

JSON 标准不支持注释（// 或 /* */）。虽然某些工具（如 VS Code 针对 tsconfig.json）允许使用注释，但标准的 JSON.parse() 会失败。

错误示例:

{
  "id": 1 // 这是一个注释
}

解决方案: 在解析前删除所有注释。如果您必须保留元数据，请使用类似于 "__comment": "text" 的属性。

2.5 特殊值：NaN, Infinity 和 Undefined

JSON 不支持 NaN, Infinity, -Infinity 或 undefined。这些是 JavaScript 特有的值。

错误示例:

{
  "value": NaN,
  "expired": undefined
}

解决方案: 使用 null 或占位字符串/数字代替。

{
  "value": null,
  "expired": null
}

2.6 控制字符和换行符

JSON 中的字符串不能包含原始控制字符（如制表符或实际的换行符），除非它们经过转义。

错误示例:

{
  "description": "这是一段
多行字符串"
}

解决方案: 使用 \n 表示换行，使用 \t 表示制表符。

{
  "description": "这是一段 \n多行字符串"
}

---

3. 进阶故障排查

3.1 BOM (字节顺序标记)

有时文件看起来完美无缺，但在位置 0 处仍抛出 SyntaxError。这通常是由文件开头隐藏的 UTF-8 BOM 字符引起的。 解决方案: 将文件重新保存为“无 BOM 的 UTF-8”格式。

3.2 未正确转义的字符

如果您的字符串包含反斜杠 (\) 或双引号 (")，则必须对它们进行转义。

• 正确: "path": "C:\\Windows\\System32"
• 正确: "quote": "他说 \"你好\""

---

4. 预防措施

1. 使用 Linter: 使用 ESLint（配合 jsonc-parser）或 VS Code 内置的 JSON 校验。
2. 自动格式化: 在保存配置文件前，始终通过格式化工具运行您的 JSON。
3. Schema 校验: 使用 JSON Schema 定义数据结构并进行程序化验证。
4. Try-Catch: 在解析动态数据时，始终将 JSON.parse() 包裹在 try...catch 块中以优雅地处理错误。

try {
  const data = JSON.parse(userInput);
} catch (e) {
  console.error("解析 JSON 失败:", e.message);
  // 向用户显示友好的错误提示
}

---

5. 常见问题 FAQ

Q: 为什么我会收到 "Unexpected token < in JSON at position 0"？

答: 这几乎总是意味着您的代码预期接收 JSON，但实际上收到了 HTML。这通常发生在 API 调用失败，服务器返回 HTML 错误页面（如 404 或 500 页面）而不是预期的 JSON 响应时。

Q: 我可以在 JSON 中使用十六进制数字吗？

答: 不可以。JSON 仅支持标准十进制数字。0xFF 会导致解析错误。请改用 255。

Q: 如何处理会导致解析器崩溃的大型 JSON 文件？

答: 对于非常大的文件，请使用“流式”解析器，如 JSONStream (Node.js) 或 ijson (Python)，它们会逐片段处理文件，而不是将其全部加载到内存中。

---

6. 快速检查工具

如果您正苦于寻找那个缺失的逗号或放错引号的位置，请使用我们的 JSON 格式化与校验工具。它能够：

• 瞬间高亮语法错误。
• 修复单引号或尾随逗号等常见问题。
• 格式化您的 JSON，使其更易于人类阅读。

---

相关错误

• 解决 'invalid base64 string' 错误
• 如何修复 JavaScript 中的 'malformed URL'
• 理解 YAML 缩进错误