JSONLint校验时提示“Unexpected token”如何排查？

Question

JSONLint 报错 “Unexpected token” 是最常见的 JSON 格式错误之一，本质是解析器在预期位置遇到了非法字符。典型原因包括：末尾多余逗号（如 `{"name":"Alice",}`）、单引号替代双引号（`{'key':'val'}`）、未转义的换行或控制字符（如字符串内直接换行）、Unicode BOM 头（\uFEFF）、注释残留（`// 注释` 或 `/* ... */`）、以及键名未加引号（`{name: "Alice"}`）。排查建议：① 复制 JSON 到编辑器（如 VS Code），开启“显示不可见字符”；② 使用支持 JSON 语法高亮和实时校验的 IDE，快速定位红标位置；③ 检查报错行号前后——实际错误常在上一行（如漏写 `}` 导致下一行首个字符被误判）；④ 对动态生成 JSON 的代码，添加 `JSON.stringify()` 前的日志输出，确认原始数据结构。切忌手动拼接 JSON，应始终使用标准序列化方法。

Answer 1

```html

一、现象层：识别“Unexpected token”错误的表征特征

JSONLint 报错 “Unexpected token X at position Y” 是前端调试与后端 API 集成中最高频的阻断性错误。它并非语义错误，而是 JSON 解析器在严格语法校验阶段触发的词法解析失败——即读取到一个在当前上下文完全不合法的字符（如 , 出现在对象末尾、' 替代 "、或裸露的换行符）。该错误常伴随模糊行号（如报第15行，实则第14行缺闭合括号），极易误导开发者陷入“逐行盲查”陷阱。

二、语法层：JSON 标准（RFC 8259）强制约束的六大非法模式

• 尾逗号（Trailing comma）：{"name": "Alice",} —— 合法于 JavaScript 对象，但违反 JSON 规范；
• 单引号字符串：{'key': 'val'} —— JSON 仅允许双引号包裹字符串字面量；
• 未转义换行：{"msg": "Hello↵World"}（↵为真实换行）—— 必须写作 "Hello\\nWorld"；
• BOM 头干扰：\uFEFF{"data":1} —— UTF-8 BOM（0xEF 0xBB 0xBF）被解析为非法首字符；
• 注释残留：{"id": 1 // active} 或 /* config */ {"mode": "dev"} —— JSON 无注释语法；
• 未引号键名：{name: "Alice"} —— 所有键名必须是双引号字符串，不可省略。

三、溯源层：动态生成场景下的隐蔽错误链

当 JSON 来自模板拼接、日志注入或配置合并时，错误常源于上游数据污染。例如 Node.js 中：
const payload = `{ "user": "${req.body.name}", "ts": ${Date.now()} }`;
若 req.body.name 含双引号或换行，将直接破坏结构。此时错误不在 JSONLint 输入文本本身，而在生成逻辑的输入校验缺失与序列化方式错误。

四、诊断层：四维交叉验证排查法

维度	工具/操作	关键洞察
可视化	VS Code 开启 editor.renderWhitespace: "all"	暴露 BOM、零宽空格（U+200B）、制表符等不可见字符
实时反馈	WebStorm / VS Code JSON 插件 + ESLint-plugin-json	红波浪线下划线精准定位 token 边界（如 "key" 末尾缺失 "）

五、防御层：工程化 JSON 安全实践体系

graph LR
A[原始数据] --> B{是否经 JSON.stringify?}
B -->|否| C[❌ 风险：手动拼接/模板注入]
B -->|是| D[✅ 安全基线]
D --> E[前置校验：JSON.parse(JSON.stringify(x)) === x?]
E --> F[后置加固：strip-bom + json5.parse 兼容性兜底]

六、进阶层：解析器底层视角——为什么报错位置常偏移？

JSON 解析器（如 Esprima、Acorn）采用递归下降分析器，错误定位依赖当前解析栈状态。典型偏移案例：

{
  "items": [
    {"id": 1},
    {"id": 2}  ← 缺少 ], 缺失导致下一行 { 被误判为“unexpected '{'”
  }
  "total": 2
}

此时解析器在期待 ] 却收到 {，故报错指向该 { —— 实际病灶在上一行末尾。此机制要求开发者建立“错误总在期望落空处之前”的逆向思维。

七、生产层：CI/CD 流水线中的 JSON 健康检查

在 Git Hook 或 GitHub Actions 中嵌入自动化校验：
npx jsonlint --quiet config.json || echo "❌ JSON syntax violation in config.json"
配合 jq -e . config.json >/dev/null 双引擎验证，避免单一工具解析器差异导致漏检。对 Swagger/OpenAPI 文件等 JSON Schema 场景，需额外集成 speccy lint 进行语义级校验。

```