题图: 电脑屏幕上显示的彩色源代码。摄影:Markus Spiske(Pexels,免费使用)

每个开发者都盯过同一堵文字墙:几千字符的单行 JSON,bug 藏在某个不匹配的括号和一个看不见的尾逗号之间。JSON 是 Web 的默认数据格式——API、配置文件、日志,如今还有 LLM 函数调用,全都在说 JSON。但它依然消耗着不成比例的调试时间,恰恰因为它看起来太简单。

本指南介绍 JSON 是什么、最浪费时间的高频语法错误,以及格式化、压缩、校验的规范工作流。本站免费的 JSON 格式化与校验器完全在浏览器内运行——粘贴内容,一键完成格式化、压缩或校验。

一分钟看懂 JSON

JSON(JavaScript Object Notation)是一种结构化数据的文本格式。值类型只有六种:对象 {}、数组 []、字符串、数字、布尔值和 null。这就是全部语言——JSON 的强大之处在于没有注释、没有变量、没有逻辑,对机器无歧义,格式化后对人类也可读。

这种极简也正是陷阱所在:JSON 比 JavaScript 更严格,大多数「JSON 错误」其实是 JavaScript 习惯的渗漏。三条被反复违反的语法规则:

  1. 键名必须用双引号。 {name: "AI"} 是 JavaScript 对象,不是 JSON
  2. 字符串必须用双引号。 {'a': 1} 非法——JSON 里不存在单引号
  3. 禁止尾随逗号。 [1, 2, 3,] 和 {"a": 1,} 都非法

最浪费调试时间的五类错误

1. 尾随逗号。 手写 JSON 中最常见的错误,也是字符串拼接生成的 API 请求体里最恼人的错误。解决办法很机械:格式化文档,检查每个数组和对象的最后一个元素。

2. 引号与控制字符未转义。 字符串内的 " 必须写成 \",字符串内的真实换行必须写成 \n。从 HTML 抓取或从 Word 复制的数据最容易违反这条规则。

3. 混入注释。 JSON 没有注释。从 JavaScript 配置文件里带过来的 // 或 /* */ 会产生解析错误。需要注释就用 JSONC(VS Code 使用的带注释 JSON),但要记住标准解析器会拒绝它。

4. 数字格式违规。 前导零(01)、末尾小数点(1.)、十六进制、NaN/Infinity 全部非法。来自电子表格的数字字符串常常带前导零。

5. BOM 与不可见字符。 文件开头的 UTF-8 字节序标记(U+FEFF),或从聊天软件粘贴进来的零宽空格,会在看似空白的行上产生让人抓狂的 “unexpected token” 错误。

这五类错误都能被 JSON 格式化工具的校验功能用浏览器原生 JSON.parse 即时捕获,并报告精确的错误位置。

预防错误的格式化工作流

格式化不是门面功夫。美化排版能把 4,000 字符的单行文本变成可阅读的树状结构,而「能读出来」正是错误在上线前暴露的方式。工作流如下:

  1. 先格式化。 用 2 或 4 空格缩进。永远不要诊断单行文档——视觉结构是调试的一部分
  2. 再校验。 确认文档能解析。失败时错误信息里包含位置
  3. 做 diff。 比较 API 响应时,先把双方压缩再 diff——空白和键序差异会消失
  4. 发送前压缩。 压缩后的请求体更小,带宽更省,对计量计费的 API 而言账单 token 也更少。几乎所有 LLM API 调用的请求体都是 JSON,压缩后的请求比美化版小 20–30%

为什么 AI 时代 JSON 更重要

JSON 已从 AI 应用开发的边缘走向中心。它现在主导三个位置:

聊天 API。 OpenAI 兼容端点收发 {"messages": [...]} 数组。每个请求体和响应都是 JSON,格式错误的请求体是除限流外调用失败最常见的原因。

函数调用。 LLM 调用工具时,参数以 JSON 对象的形式交给你的代码解析。模型输出带尾逗号的 {"city": "Tokyo",} 会直接让严格解析器崩溃——这也是保证有效 JSON 的结构化输出模式成为生产集成默认方案的原因之一。

结构化输出。 JSON Schema 约束生成强制模型只输出有效文档。但 schema 本身也是 JSON,200 行 schema 里的一个语法错误和请求体里的错误一样致命。

一个实用的组合:用 JSON 工具格式化并校验请求体,再用 Token 费用计算器估算执行成本。两个工具一起覆盖 API 调用的完整生命周期——构建、验证、定价。

JSON 与替代格式的取舍

  • JSON — API 和配置的默认选择,没有特殊理由就用它
  • JSONL(JSON Lines) — 每行一个 JSON 对象,是 OpenAI 批量文件和流式数据集的格式
  • YAML — 人写的配置(Ansible、CI 流水线)。支持注释但对空白敏感
  • TOML — Rust、Go、Hugo 的配置格式(本站配置就是 TOML)。扁平配置比 YAML 更简单
  • Protobuf / MessagePack — 解析速度优先于可读性的高吞吐内部服务二进制格式

共同点:它们都是结构化的,你在 JSON 调试中练出的技能可以直接迁移。

编辑器格式化与在线工具的分工

你并不总是需要浏览器工具。每个主流环境都内置了格式化器,了解全部四种选择,就能按场景选最快的:

  • VS Code:打开 .json 文件后执行「格式化文档」(macOS Shift+Option+F,Windows Shift+Alt+F)。内置 JSON 语言模式会美化排版并内联标出语法错误。JSON 已是文件时这是最快的方式。
  • jq:命令行瑞士军刀。echo '{"a":1}' | jq . 美化输出,jq -c . 压缩;jq 拒绝解析非法 JSON,因此兼任校验器。shell 管道和日志追踪必备。
  • Python:python3 -m json.tool file.json 输出美化结果——只要有 Python 就能用,无需安装。
  • 浏览器工具:JSON 出现在聊天消息、邮件或工单里时的正解——粘贴、点一下、完成。AI Forward 的 JSON 格式化与校验器覆盖此场景,并提供带精确错误位置的校验。

编辑器格式化器通常给不了的是精确的错误信息:大多只是给整行画下划线。文档损坏严重时,先用能报告精确字符偏移的校验器定位,再动手修。

HTTP 层面的 JSON:请求头与响应

格式化在 HTTP 层同样重要,而 API 调试的大部分时间花在两个请求头错误上:

1. Content-Type 写错。 JSON 请求体必须以 application/json(可加 ; charset=utf-8)发送。用浏览器默认的 application/x-www-form-urlencoded 发送,会导致服务端解析失败或静默误读。典型症状:服务器把你的 JSON 当成一个字符串字段接收。

2. 缺少 Accept 头。 不发送 Accept: application/json 的客户端,收到的是 HTML 错误页而不是 JSON 错误体,下游的响应解析器随之崩溃。规范的 API 会返回机器可读的错误——RFC 7807 的 application/problem+json——但只在被要求时才返回。

API 工作的两个习惯:

  • 先压缩再传输。 压缩后的 JSON 比美化版更容易被 gzip 压小。大请求体先压缩,其余交给服务器的 Content-Encoding: gzip。对计量计费的 LLM API,更小的请求体也意味着更少的计费 token。
  • 把响应解析视为不可信输入。 永远不要用正则或字符串切片手工解析 JSON——一律使用平台的 JSON.parse 等价物并加错误处理。响应流里混进的 500 字符错误页,应当留下一条干净的日志,而不是打崩一个 worker。

让格式化器提速的三个工作流

日志。 现代服务输出 JSON Lines——每行一个结构化对象。这里的标准工具是 jq:tail 一个日志文件,管道接到 jq 'select(.level == "error")',噪音立刻消失。同样的 JSONL 知识可以直接迁移到 LLM 批量文件——它们使用完全相同的每行一对象格式。

配置文件。 package.json、settings.json、tsconfig.json 时刻都在手工编辑。格式化器能在你新增条目的一瞬间抓住尾逗号;校验器能在你弄坏文件的瞬间抓住它。注意 VS Code 的 settings.json 是 JSONC(允许注释)——含注释时用严格 JSON 工具格式化会失败,这本身就是一个有用的信号:提醒你正在编辑的到底是哪种格式。

LLM 请求体。 聊天补全请求是 JSON,函数调用参数是 JSON,JSON Schema 输出约束也是 JSON。发送前先校验;测量成本前先压缩——Token 费用计算器按你实际发送的内容计量,压缩后的 JSON 算出来的数字更低。两个工具配合,是从「一个 JSON 问题」到「一个已解决的问题」的最短路径。

JSON Schema:从校验到结构化输出

至此我们把 JSON 当作需要人工检查的文档。工业级的升级是 JSON Schema:一份用 JSON 写成的、正式描述另一份 JSON 文档「应该长什么样」的文档。有了 schema,校验器能在毫秒内判断请求体是否正确;更进一步,还能约束 LLM 只产出正确的请求体。

一个最小 schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "tags": { "type": "array", "items": { "type": "string" } },
    "active": { "type": "boolean" }
  },
  "required": ["name", "active"],
  "additionalProperties": false
}

这份 schema 说的是:一个含非空 name 字符串、字符串数组 tags、布尔值 active 的对象——除此之外什么都不许有。工具:JavaScript 用 ajv,Python 用 jsonschema,或 OpenAPI 工具链内置校验。schema 承担三个职责:

  1. 固化契约。 schema 是 API 预期的可执行文档——同一份文件驱动校验、代码生成和测试
  2. 在边界快速失败。 入口处校验一次,下游所有组件就能假定数据格式良好,不必反复检查
  3. 约束 LLM 输出。 OpenAI 的结构化输出模式接收 JSON Schema,保证模型响应能按 schema 解析;DeepSeek 等也提供带 schema 支持的 JSON 模式。在生产函数调用中,schema 约束输出已从最佳实践变成默认做法——它把「模型返回了无法解析的内容」从预期内的失败变成了配置错误

节省调试时间的 schema 设计要点:尽量保持 schema 小而扁平;状态字段优先用 enum 而非自由字符串;永远设置 additionalProperties: false——把这一个开关加上,宽松检查才真正变成契约。schema 变大之后,先校验 schema 本身:一份带尾逗号的 200 行 schema,失败症状和模型错误一模一样,而 JSON 格式化器能一键揪出真正的原因。

JSON 的意外陷阱:每个开发者都会遇到的规范怪癖

JSON 比看上去更简单,也因此有四个规范级怪癖,连用了多年的开发者也会中招:

数字精度。 JSON 数字通常被解析为 IEEE 754 双精度浮点数,超过 2⁵³ 的 64 位整数会静默丢失精度。经典受害者是 Snowflake 风格的 ID:9223372036854775807 变成 9223372036854776000。解法与 Twitter API 等系统一致——把需要精度的整数当字符串传输。

重复键。 {"a": 1, "a": 2} 语法上完全合法,规范说哪个值生效由实现决定——多数解析器静默保留最后一个。校验器抓不到它(语法没错),而它是手工合并请求体的标志性 bug。格式化后肉眼检查是唯一可靠的防线。

键的顺序。 对象键序没有语义,但 diff 工具不知道。比较 API 响应时先排序键(jq -S)或压缩后再 diff,否则每次响应都会出现虚假差异。

字符串只有双引号。 单引号、反引号模板字符串、末尾的隐形空白,全是 JavaScript 习惯导致的解析失败。当错误莫名其妙时,先怀疑引号——这一步能修好比其他任何单点改动都多的解析失败。

一次 JSON 调试实录:分步拆解

理论很便宜,来看一次贴近真实的完整调试。工单说集成挂了,请求体是脚本里字符串拼接出来的:

{"user": "O'Brien", "plan": "pro", "features": ["sso", "audit-log",]}

这里有两个 bug——未转义的引号和尾随逗号——它们会在不同阶段失败。规范流程:

  1. 先校验。 粘贴进 JSON 格式化与校验器。解析器报告 features 数组里的尾随逗号并给出精确位置(双引号 JSON 里 "O'Brien" 中的撇号其实是合法的——真正的错误是尾随逗号)
  2. 再格式化。 删掉逗号后美化排版。嵌套结构一目了然;如果是拼接时被截断的请求体,这里会暴露对象没有闭合
  3. 对照预期 schema 做 diff。 把格式化结果与文档示例比较。校验器发现不了的键名拼错(如 featurs)在这里现形
  4. 压缩后发送。 修正后的请求体压缩后交给 API——这时 Token 费用计算器也能算出诚实的成本

这个模式适用于一切 JSON 事故:校验找语法错误,格式化看结构,diff 找语义错误,压缩后上线。四步、各配一个工具、零猜测。

常见问题


工具行为已按 ECMAScript JSON.parse 规范验证。JSONL、JSONC、TOML 的描述基于 2026 年 11 月现行公开规范。