总结 8 种最常见的 JSON 语法报错（Unexpected token）及自动化修复方案

一、 解析器机制与 Unexpected Token 的本质

JSON 语法是一种严格的上下文无关文法。解析器在按字符扫描 JSON 字符串时，内部维护着一个严格的状态机（如等待键名、等待冒号、等待值、等待逗号或闭合括号）。

一旦在某一个状态遇到不合规字符，解析器会立即终止扫描，并抛出 SyntaxError: Unexpected token <character> in JSON at position <N>。其中 <N> 代表出错字符在整个输入字符串中的 0-indexed 字符索引。

技术团队应当在持续集成流水线中建立自动化回归测试、代码静态扫描规则与监控预警防线，在研发早期及时捕获并消除边界隐患。

研发人员需要对首屏可交互时间（TTI）、主线程阻塞耗时（TBT）以及高并发负载下的峰值内存占用进行全方位监控。通过

• 建立完善的自动化回归测试用例，覆盖边界极端场景。
• 在研发规范中明确字段与接口类型的命名约束，降低沟通成本。
• 定期审查生产监控日志，及时处置潜在的异常报错。

二、 8 类高频 JSON 报错根因拆解与修复方案

以下是生产环境中最常见的 8 种错误情形：

1. Unexpected token 'o' in JSON at position 1：最经典的错误！通常是因为对已经解析好的 JavaScript 对象重复调用了 JSON.parse(obj)。对象被隐式转为 [object Object]，解析器在 index 1 遇到了字符 'o'。

2. Unexpected token '<' in JSON at position 0：说明请求接口返回的根本不是 JSON，而是 HTML 网页！通常是由于 API 路径写错导致 404、接口崩溃返回 500 HTML 报错页、或网关未登录跳转到了 HTML 登录页。

3. Unexpected token ''', '...' is not valid JSON：使用了单引号。标准 JSON 规范要求对象键名与字符串值必须强制使用双引号包裹。

4. Unexpected token '}' 或 ']' (尾随逗号 Trailing Comma)：在对象最后一个属性或数组最后一个元素末尾多写了逗号。例如 {"a": 1,}。

5. Unexpected token in JSON at position 0 (BOM 头问题)：文件保存时带有 UTF-8 BOM 标记（\uFEFF）。肉眼不可见，但 JSON.parse 会因为开头的隐藏字节报错。

6. 键名未用双引号包裹：如 { key: "value" }。JavaScript 对象字面量允许省略引号，但合法 JSON 语法严格禁止。

7. 包含未转义的控制字符或换行符：字符串中直接包含多行回车或制表符，未写成 \n 或 \t。

8. 复制或拼接时混入了 JS 注释：JSON 规范完全不支持 // 单行注释或 /* */ 多行注释。

技术团队应当在持续集成流水线中建立自动化回归测试、代码静态扫描规则与监控预警防线，在研发早期及时捕获并消除边界隐患。

研发人员需要对首屏可交互时间（TTI）、主线程阻塞耗时（TBT）以及高并发负载下的峰值内存占用进行全方位监控。通过

• 建立完善的自动化回归测试用例，覆盖边界极端场景。
• 在研发规范中明确字段与接口类型的命名约束，降低沟通成本。
• 定期审查生产监控日志，及时处置潜在的异常报错。

// 典型错误代码示例：
// 1. 重复解析对象
const data = { id: 1 };
JSON.parse(data as any); // 报错: Unexpected token o in JSON at position 1

// 2. 尾随逗号
JSON.parse('{"name": "JSON", "version": 1,}'); // 报错: Unexpected token } in JSON...

// 3. 单引号
JSON.parse("{'age': 18}"); // 报错: Unexpected token ' in JSON...

三、 诊断调试三步法：精准定位 Position 物理位置

当遇到复杂的千行 JSON 报错时，肉眼扫描极度低效。推荐使用以下 3 步自动化代码精准定位异常点：

第一步：拦截原始 Payload，防止被框架隐式转换丢失现场；

第二步：根据 Error 对象中的 position 编号，截取前后 30 个字符的物理上下文；

第三步：打印异常字符的 charCodeAt() / Unicode 码位，让不可见字符（如 BOM 头、零宽空格）无所遁形。

技术团队应当在持续集成流水线中建立自动化回归测试、代码静态扫描规则与监控预警防线，在研发早期及时捕获并消除边界隐患。

研发人员需要对首屏可交互时间（TTI）、主线程阻塞耗时（TBT）以及高并发负载下的峰值内存占用进行全方位监控。通过

• 建立完善的自动化回归测试用例，覆盖边界极端场景。
• 在研发规范中明确字段与接口类型的命名约束，降低沟通成本。
• 定期审查生产监控日志，及时处置潜在的异常报错。

function diagnoseJsonError(jsonString: string) {
  try {
    return JSON.parse(jsonString);
  } catch (err: any) {
    console.error("JSON 解析失败:", err.message);
    
    // 匹配 position 索引
    const posMatch = err.message.match(/position (\d+)/);
    if (posMatch) {
      const pos = parseInt(posMatch[1], 10);
      const start = Math.max(0, pos - 20);
      const end = Math.min(jsonString.length, pos + 20);
      
      const snippet = jsonString.slice(start, end);
      const targetChar = jsonString[pos];
      
      console.log(`上下文区间 [${start}..process..${end}]: "${snippet}"`);
      console.log(`错误字符位置 [${pos}]: '${targetChar}' (Unicode 码位: U+${targetChar?.charCodeAt(0).toString(16).padStart(4, '0')})`);
    }
  }
}

线上避坑：大 JSON 解析卡顿与边界类型丢精度排查

在前端处理超过 50MB 的超大 JSON 数据时，直接在主线程调用 JSON.parse 会导致页面死锁卡顿几百毫秒甚至崩溃。解决办法是把文本数据交给 Web Worker 在后台子线程解析，解析完成后再把对象以 Transferable Objects 方式传回主线程。

另一个常见的隐蔽 Bug 是 JavaScript 的 64 位双精度浮点数精度限制。超过 9007199254740991 (Number.MAX_SAFE_INTEGER) 的订单 ID 或雪花 ID，在 JSON.parse 时末尾数字会被悄悄改变。对于这种长整数，后端接口必须返回字符串格式，或者前端引入 json-bigint 库进行安全反序列化。

• 超大 JSON 解析切勿在主线程硬扛，优先使用 Web Worker。
• 超过 16 位的长整型 ID 必须转为字符串传输，防止精度丢位数。
• 使用 Try...Catch 包裹 JSON.parse，防止非法语法导致页面白屏。