JSON 格式化：开发者最容易犯的 5 个错误

如果有一次我因为初级开发把格式有误的 JSON 塞进 API 然后对着 500 报错发呆就有一块钱，我现在已经能买一台很不错的咖啡机了。大概两台。

JSON 看起来很简单——键值对、花括号，完事。但它对语法的要求出奇地严格，而且报错信息也没什么帮助。以下是我最常遇到的五个错误，附上具体示例和修复方法。

1. 尾部逗号 — JSON 的头号杀手

❌ 错误写法

这个几乎坑了所有习惯写 JavaScript 的人。在 JS 里，尾部逗号没问题。但在 JSON 里？解析器每次都会报错。

{
  "name": "Alice",
  "age": 30,
  "email": "[email protected]",
}

看到最后一个值后面的逗号了吗？这是个语法错误。JSON 规范不允许尾部逗号，毫无例外。你的解析器会抛出类似 SyntaxError: Unexpected token } in JSON at position 48 或 unexpected end of JSON input 的错误。

✅ 正确写法

{
  "name": "Alice",
  "age": 30,
  "email": "[email protected]"
}

去掉尾部逗号就行了。或者更好的做法：用 JSON 格式化工具自动检测这个问题。大多数靠谱的格式化器会高亮标出那个多余的逗号。

一个小技巧：很多代码编辑器支持在保存时自动移除尾部逗号，作为 linter 配置的一部分。设置好之后，你基本不会再踩这个坑。

2. 用单引号代替双引号

❌ 错误写法

这又是一个让 JavaScript 开发者中招的坑。在 JS 里，'string' 和 "string" 都可以。但 JSON 只接受双引号。

{
  'name': 'Alice',
  'active': true
}

这会报 Expected double-quoted property name 或类似的错误，具体取决于你的解析器。有时候错误信息更模糊，那就更有意思了。

✅ 正确写法

{
  "name": "Alice",
  "active": true
}

键用双引号，字符串值也用双引号。没有例外。不管是值还是属性名，只要是字符串，就必须用双引号。

我曾经见过一个配置文件，有人全部用了单引号，然后花了一个小时调试为什么 Go 程序解析不了。Go 的 JSON 解析器报错信息可没那么详细。别做那个人。

3. JSON 不支持注释

❌ 错误写法

想在 JSON 文件里加注释？没门。JSON 规范不支持注释。每次都会有人被这个事实 surprise 到。

{
  // 用户配置
  "name": "Alice",
  "theme": "dark" // 可选 "light" 或 "dark"
}

这会静默失败或直接报解析错误。JavaScript 的 JSON.parse() 会返回 Unexpected token / in JSON at position 2。如果你没在留意这个，还真不容易发现。

✅ 替代方案

你有三个选择：

1. 用 JSON5 解析器 — JSON5 支持注释、尾部逗号和单引号。大多数语言都有对应的库。
2. 加一个 "_comment" 字段 — 丑但管用："_comment": "主题可设为 dark 或 light"。只是记得发送给线上 API 之前要删掉它。
3. 注释写在别处 — 在 JSON 文件旁边维护一个 README 或说明文件。不太方便，但保持了 JSON 的干净。

我见过有人在线上配置文件里写了 "// 遗留字段，请勿删除" 作为实际的键名。千万别这么干。

4. BOM 和编码问题

❌ 问题场景

这是最隐蔽的 JSON 错误，因为肉眼看完全没问题。你在记事本里打开文件，看起来完美无缺。尝试解析，什么都不对。

罪魁祸首通常是文件开头的 BOM（字节顺序标记）。某些编辑器——尤其是在 Windows 上——保存文件时会自动添加 UTF-8 BOM（EF BB BF）。JSON 解析器看到开头的 { 前面有三个不可见字节，完全不知道该怎么处理。

// 你看到的是这样：
{ "name": "张三" }

// 但实际字节以 EF BB BF 开头，解析器看到的是：
[byte-order-mark]{ "name": "张三" }

报错信息？大概类似 Unexpected token \u00ef in JSON at position 0 这种毫无用处的东西。Position 0。就是第一个字节。凌晨 2 点来调这个 bug，祝你好运。

✅ 解决方法

• 保存时不带 BOM — 在 VS Code 中，看右下角的编码指示器。如果显示"UTF-8 with BOM"，点击它切换为"UTF-8"。
• 用十六进制编辑器 检查是否存在 BOM 字节。
• 程序化去除 BOM — 如果你在消费 API 响应，在解析前检查并去除前三个 EF BB BF 字节。

相关问题：如果文件不是以 UTF-8 保存的（比如 GB2312 或 Windows-1252），包含非 ASCII 字符时会导致解析错误。务必确保你的 JSON 文件以不带 BOM 的纯 UTF-8 保存。

5. 嵌套太深导致难以维护

⚠️ 不是语法错误，但应该是

严格来说这不会报解析错误。但它给你带来的痛苦远超任何语法 bug。

{
  "company": {
    "departments": {
      "engineering": {
        "teams": {
          "frontend": {
            "members": {
              "alice": {
                "role": "senior",
                "skills": ["React", "TypeScript"],
                "manager": {
                  "name": "Bob",
                  "role": "tech-lead",
                  "manager": {
                    "name": "Carol",
                    "role": "VP"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

如果你想访问 Alice 的技能，你得写 data.company.departments.engineering.teams.frontend.members.alice.skills。维护这种代码？漏一层就对着 Cannot read property of undefined 报错调 20 分钟。

✅ 扁平化

重新设计你的数据结构，避免深层嵌套。几个思路：

1. 用数组 + 引用 — 把实体拆成数组，用 ID 关联，类似关系型数据库的做法。
2. 扁平化键路径 — 用点号分隔的键："frontend.alice.role"。
3. 拆分成多个文件 — 没有规定说你必须把所有数据放在一个 JSON 里。

经验法则：如果嵌套超过 3-4 层，你大概率需要重新考虑数据结构。未来的你会感谢你现在的。

快速修复：用真正的 JSON 格式化工具

如果在使用前先把 JSON 丢给一个靠谱的格式化器和验证器，上面这些问题就都成了小事。好的格式化器会自动检测尾部逗号、标出编码问题、秒速定位语法错误。

这正是我们构建 Vaultool JSON 格式化工具的原因——它在浏览器中直接验证、格式化并标出错误，不需要把你的数据上传到任何地方。把有问题的 JSON 粘贴进去，立刻看到哪里出了问题，修改后直接复制干净的版本。