JSON 错误调试完全指南

JSON 错误的常见来源

JSON 错误通常来自以下几个来源：手动编辑 JSON 时引入的语法错误；代码拼接 JSON 字符串时处理不当；从其他格式（如 JavaScript 对象字面量）转换时携带了 JSON 不支持的语法；编码问题导致的无效字符；第三方 API 返回的格式错误的响应；配置文件被手动修改后引入了错误。

理解错误来源有助于在调试时有的放矢，而不是盲目地在整个 JSON 中寻找问题。

错误消息解读：各语言的 JSON 错误

JavaScript：JSON.parse() 抛出 SyntaxError: Unexpected token X in JSON at position N，其中 N 是字符偏移量（从 0 开始），X 是意外的字符。

Python：json.loads() 抛出 json.decoder.JSONDecodeError: Expecting X: line Y column Z (char N)，直接给出行号和列号，更易定位。

Go：json.Unmarshal() 返回 &json.SyntaxError{Offset: N}，包含字节偏移量。

Python 的错误信息最友好（直接给出行列号），JavaScript 给的是字符偏移量（需要数字符，或用文本编辑器定位），Go 的最简略。

调试步骤：系统性排查方法

1. 获取完整错误信息：确保你看到了完整的错误消息，包括行号/位置信息，不要只看"JSON parse error"就停止。
2. 隔离问题 JSON：将出错的 JSON 字符串记录下来（log 出来），确保你调试的是实际出错的数据，而不是你以为它应该是什么样的。
3. 使用在线验证工具：将 JSON 粘贴到在线格式化/验证工具，工具会精确指出错误位置和类型。
4. 检查常见错误点：重点检查错误位置前后的逗号、引号、括号是否正确。
5. 逐段测试：对于大型 JSON，可以从一个已知正确的部分开始，逐步添加内容，找到引入错误的具体位置。

不可见字符：最难排查的问题

有时 JSON 看起来完全正确，却仍然解析失败，原因可能是不可见字符：BOM（Byte Order Mark，字节顺序标记）有时会被附加在 UTF-8 文件开头（尤其是 Windows 上创建的文件），JSON 解析器无法处理这个字符；零宽空格（Zero-Width Space，U+200B）偶尔会出现在从网页复制的文本中；HTML 实体（如 &、"）出现在应该是普通 JSON 的地方，通常是因为 JSON 被错误地进行了 HTML 转义。

解决方法：使用十六进制编辑器查看文件的实际字节内容；在格式化工具中显示不可见字符；用代码去除 BOM：text.replace(/^\uFEFF/, '')（JavaScript）。

API 响应 JSON 错误的调试

当 API 响应的 JSON 解析失败时，需要先检查几个前提：HTTP 响应状态码是否是 200？非 200 响应（如 404、500）可能返回 HTML 错误页面而不是 JSON；Content-Type 响应头是否是 application/json？如果服务器返回了错误，可能响应的是 text/html；响应体是否为空？空响应体不是有效的 JSON。

在 Chrome 开发者工具的 Network 面板中，可以直接查看响应的原始文本（Raw）和解析后的 JSON（Preview）。如果 Preview 标签显示错误，切换到 Raw 标签查看原始响应内容，通常能快速找到问题所在。

代码生成 JSON 时的常见错误

在代码中手动拼接 JSON 字符串是最容易出错的做法。正确的做法是始终使用语言内置的 JSON 序列化方法（JSON.stringify()、json.dumps()、json.Marshal()），而不是字符串拼接：

// 错误做法 / Wrong:
const json = '{"name": "' + name + '", "age": ' + age + '}';
// 如果 name 包含双引号或换行，会产生无效 JSON

// 正确做法 / Correct:
const json = JSON.stringify({name, age});
// JSON.stringify 会自动处理所有特殊字符的转义

防御性编程：优雅处理 JSON 错误

在生产代码中，JSON 解析应该包裹在 try-catch 中，并提供有意义的错误信息：

function safeParseJSON(str, context = '') {
  try {
    return { data: JSON.parse(str), error: null };
  } catch (e) {
    console.error(`JSON parse failed [${context}]:`, e.message);
    console.error('Raw input (first 200 chars):', str?.slice(0, 200));
    return { data: null, error: e.message };
  }
}

记录原始输入的前 200 个字符（不记录全部，避免日志过大）是排查 JSON 问题的有效手段，在生产环境中可以帮助快速定位问题根因。