JSON 解析报错 Unexpected token？5 种常见原因和修复方法

SyntaxError: Unexpected token 大概是前端和后端开发者遇到最多的 JSON 解析错误了。浏览器报 Unexpected token , in JSON at position 42，Node.js 报 Unexpected token } in JSON at position 128——看着位置信息，却经常找不到问题在哪，这时候一个能精确定位语法错误的 JSON Formatter 就能帮上忙。

其实 JSON 的语法非常严格，导致解析失败的原因基本就那么几种。本文把最常见的 5 种 json 解析错误整理出来，每种都给出错误示例和修复方法。JSON 能正常解析后，还可以用 JSON Schema Validator 进一步校验数据结构。

原因一：尾随逗号（Trailing Comma）

这是最高频的错误。JavaScript 对象允许尾逗号，但 JSON 不允许。

// 错误：最后一个元素后面多了逗号
{
  "name": "ToolVault",
  "version": "2.0",
  "features": ["formatter", "validator",],
}

报错信息通常是 Unexpected token } in JSON 或 Unexpected token ] in JSON，因为解析器在逗号后面期望下一个值，却遇到了闭合符号。

// 正确：去掉尾逗号
{
  "name": "ToolVault",
  "version": "2.0",
  "features": ["formatter", "validator"]
}

常见场景：从 JavaScript 代码中复制对象字面量当作 JSON 使用时，特别容易带上尾逗号。

原因二：使用单引号

JSON 标准只允许双引号，单引号会直接报错 Unexpected token ' in JSON。

// 错误：用了单引号
{
  'name': 'ToolVault',
  'description': 'A developer tool'
}

// 正确：全部使用双引号
{
  "name": "ToolVault",
  "description": "A developer tool"
}

常见场景：从 Python 的 dict 输出或 YAML 转换过来时，容易保留单引号习惯。

原因三：未转义的特殊字符

JSON 字符串中的某些字符必须转义，否则解析器会认为字符串提前结束了。

// 错误：字符串中包含未转义的双引号和换行
{
  "message": "He said "hello" to me",
  "path": "C:\new\test"
}

第一个问题："hello" 中的双引号没有转义，解析器在 He said 后就认为字符串结束了。第二个问题：\n 和 \t 会被解释为换行符和制表符。

// 正确：转义特殊字符
{
  "message": "He said \"hello\" to me",
  "path": "C:\\new\\test"
}

需要转义的字符：" → \"、\ → \\、换行 → \n、制表符 → \t、回车 → \r。

常见场景：拼接 JSON 字符串时没有对变量值做转义处理，或者 Windows 路径直接塞进 JSON。

原因四：BOM 头（Byte Order Mark）

这是一个隐蔽的问题。UTF-8 文件开头可能有 BOM 字符（\uFEFF），肉眼不可见，但 JSON 解析器会报 Unexpected token in JSON at position 0。

// 模拟带 BOM 的 JSON 字符串
const jsonWithBOM = "\uFEFF{\"name\": \"test\"}";

JSON.parse(jsonWithBOM);
// SyntaxError: Unexpected token  in JSON at position 0

// 修复：去掉 BOM
const clean = jsonWithBOM.replace(/^\uFEFF/, "");
JSON.parse(clean); // { name: "test" }

常见场景：Windows 记事本保存的 UTF-8 文件默认带 BOM。如果你的 JSON 来自文件读取（fs.readFile、fetch 本地文件），position 0 报错大概率是 BOM。

// Node.js 中读取 JSON 文件的安全写法
const fs = require("fs");
const raw = fs.readFileSync("config.json", "utf-8");
const data = JSON.parse(raw.replace(/^\uFEFF/, ""));

原因五：JSON 中包含注释

JSON 标准不支持任何形式的注释。// 和 /* */ 都会导致解析失败。

// 错误：包含注释
{
  // 这是服务器地址
  "host": "api.example.com",
  "port": 8080 /* 默认端口 */
}

报错通常是 Unexpected token / in JSON at position X。

// 正确：删除所有注释
{
  "host": "api.example.com",
  "port": 8080
}

常见场景：把 .jsonc（VS Code 配置格式）或带注释的配置文件直接当 JSON 解析。如果你确实需要注释，考虑使用 JSON5 格式或 YAML。

// 如果必须处理带注释的 JSON，先正则去除（简单场景）
const stripComments = (str) =>
  str.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");

JSON.parse(stripComments(jsonWithComments));

快速定位和修复

遇到 Unexpected token 报错时，按这个顺序排查：

1. 看报错的 position 数字，定位到具体字符
2. 检查该位置前后是否有上述 5 种问题
3. 如果 position 是 0，优先检查 BOM
4. 如果 JSON 是程序生成的，检查拼接逻辑中的转义处理

对于较长的 JSON，手动排查效率很低。你可以把内容粘贴到 JSON 格式化工具 中，它会在浏览器本地即时校验语法，精确标出错误位置，并自动格式化合法的 JSON。所有处理都在本地完成，不用担心接口数据或配置信息泄露到第三方服务器。

容易算错的 position

报错偏移量是解析器收到的字符串里的字符下标——不是编辑器折行后的「视觉列」，也不是混用编码时的字节偏移。JavaScript 字符串里一个多字节 UTF-8 字符仍只占一个码元下标。若 position「偏早」，先查代理是否前置了 BOM，或日志包装是否在 JSON 前塞了状态行。若 token 字面量是 <，别再纠结 JSON 语法：你多半在看 HTML 错误页（见下文相关链接）。

FAQ

Unexpected token 是什么意思？

解析器在当前位置遇到了非法字符——常见是尾逗号、单引号、未转义控制字符、文件头 BOM，或注释里的 /。

怎么修 “Unexpected token is not valid JSON”？

1. 跳到报错 position。
2. 对照上文 5 种原因。
3. 若 token 是 '<'，响应体其实是 HTML——见接口返回 HTML 的 5 种原因。
4. 粘贴到 JSON 格式化工具 可立刻高亮第一处错误。

为什么 JS 对象允许尾逗号，JSON.parse 不行？

JS 对象字面量语法 ≠ JSON。对外输出请用 JSON.stringify，或在 parse 前去掉尾逗号。

ToolVault 工具匣 出品的开发者指南。若 token 是 '<'（HTML 而非 JSON），见接口返回 HTML 的 5 种原因。相关工具：JSON 格式化、JSON Diff、JSON Schema 校验。其他在线工具可在 首页 找到。

实现注记

做 JSON 格式化工具时我们发现，最被需要的不是格式化而是报错定位：Unexpected token 没有行列号等于没说。我们给解析器包了一层错误位置提取，把 token 位置换算成行列并在原文上标出——本文的排错路径因此可以直接在工具里走完。