DevToolkit Pro

SyntaxError: Unexpected token 大概是前端和后端开发者遇到最多的 JSON 解析错误了。浏览器报 Unexpected token , in JSON at position 42，Node.js 报 Unexpected token } in JSON at position 128——看着位置信息，却经常找不到问题在哪。

其实 JSON 的语法非常严格，导致解析失败的原因基本就那么几种。本文把最常见的 5 种 json 解析错误整理出来，每种都给出错误示例和修复方法。

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

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

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

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

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

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

原因二：使用单引号

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

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

// 正确：全部使用双引号
{
  "name": "DevToolkit",
  "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。所有处理都在本地完成，不用担心接口数据或配置信息泄露到第三方服务器。