先说结论
- 浏览器里排版：把 JSON 粘贴到 FormatArc JSON 格式化器，数据全程不出本机
- 终端里排版：
echo '{...}' | jq .或python3 -m json.tool - 代码里排版：JavaScript / Node.js 用
JSON.stringify(data, null, 2)
下面按这三条路径展开，顺便把常见语法错误和工具选型也讲清楚。
JSON 排版（Pretty Print）是什么
JSON（JavaScript Object Notation）是 API 响应、配置文件、服务间数据交换中最通用的格式之一。
但为了传输效率，很多场景下 JSON 会被压成一行（minify）。人眼根本没法一眼看出嵌套结构。开发调试时，把缩进和换行加回去——也就是所谓的 pretty print（排版 / 美化）——是每天都得干的事。
常见的 JSON 语法错误
JSON 语法由两份官方规范定义：RFC 8259在新标签页中打开（IETF 标准）和 ECMA-404在新标签页中打开（ECMA 标准）。两份规范定义的语法一致，所以下面的规则不是某个格式化器的"个人偏好"，而是 JSON 规范本身的要求。
1. 尾逗号（trailing comma）
{
"name": "example",
"value": 42,
}
最后一个字段后面多了个逗号，JSON 就不合法了。JavaScript 对象字面量允许尾逗号，但标准 JSON 不允许。
2. 单引号
{'name': 'example'}
JSON 只认双引号 "。单引号 ' 不合法。
3. 键没加引号
{name: "example"}
JSON 里每个键都必须用双引号包起来。
JSON 语法错误速查表
| 错误类型 | 错误示例 | 修正方法 |
|---|---|---|
| 尾逗号 | {"a": 1,} | 删掉最后一个值后面的逗号：{"a": 1} |
| 单引号 | {'a': 'b'} | 换成双引号：{"a": "b"} |
| 键没加引号 | {a: 1} | 所有键加双引号：{"a": 1} |
| 注释 | {"a": 1} // note | JSON 没有注释语法，删掉 |
| 前导零 | {"a": 01} | 数字前不能加 0：{"a": 1} |
| 正号 | {"a": +1} | 去掉数字前的 +：{"a": 1} |
| 十六进制 / 八进制 | {"a": 0x1F} | 只允许十进制：{"a": 31} |
NaN / Infinity | {"a": NaN} | 不是合法 JSON 值，用数字或 null |
| undefined 值 | {"a": undefined} | undefined 不是 JSON 值，用 null |
| 未转义控制字符 | "..." 内有换行 | 字符串内用 \n 转义 |
| 未转义反斜杠 | {"a": "C:\path"} | 转义反斜杠：{"a": "C:\\path"} |
| 值用单引号 | {"key": 'value'} | 字符串值也要双引号：{"key": "value"} |
用 JSON.stringify() 排版
JavaScript 和 Node.js 里，JSON.stringify() 的第三个参数就是缩进。这是代码里最省事的排版方式：
const data = { name: "Alice", age: 30, roles: ["admin", "editor"] };
// 2 空格缩进
console.log(JSON.stringify(data, null, 2));
输出：
{
"name": "Alice",
"age": 30,
"roles": [
"admin",
"editor"
]
}
第二个参数是 replacer，用来过滤或转换特定字段。保留全部字段就传 null。
想用 Tab 缩进：
JSON.stringify(data, null, "\t");
JSON.stringify 的几个坑
简单对象用 JSON.stringify() 没问题，但生产代码里经常踩到下面这几个。
循环引用
对象里有一个字段指回自身或父级，JSON.stringify 会直接抛 TypeError: Converting circular structure to JSON。标准解法是传一个 replacer 函数，记录已经序列化过的对象：
function safeStringify(value, space = 2) {
const ancestors = [];
return JSON.stringify(value, function (_key, val) {
if (typeof val !== "object" || val === null) return val;
while (ancestors.length && ancestors[ancestors.length - 1] !== this) {
ancestors.pop();
}
if (ancestors.includes(val)) return "[Circular]";
ancestors.push(val);
return val;
}, space);
}
典型场景：DOM 树、状态管理库的 store、日志框架里把 request 对象又塞回去。
用 toJSON() 控制输出
JSON.stringify 会检查每个值有没有 toJSON() 方法，有就调它拿返回值。Date 自带 toJSON()，输出 ISO 8601 字符串。你自己的类也能定义：
class Money {
constructor(amount, currency) {
this.amount = amount;
this.currency = currency;
}
toJSON() {
return `${this.amount.toFixed(2)} ${this.currency}`;
}
}
JSON.stringify({ price: new Money(19.9, "USD") }, null, 2);
// 输出：{ "price": "19.90 USD" }
比序列化前再跑一遍转换逻辑干净，缩进也照常生效。
用 replacer 过滤 / 打码敏感字段
replacer 不光能处理循环引用，还能丢掉或掩码特定键。打日志时过滤密码、token 很常用：
const redactKeys = new Set(["password", "apiKey", "authorization"]);
JSON.stringify(response, (key, value) => redactKeys.has(key) ? undefined : value, 2);
也可以直接传一个要保留的键名数组：
JSON.stringify(user, ["id", "email", "createdAt"], 2);
Prettier 和 JSON.stringify 怎么选
prettier 是跨语言代码格式化器（TypeScript、CSS、Markdown、JSON 都支持）。项目里已经用了 Prettier 的话，.json 文件跑 prettier --write file.json 就能按项目统一设置来排。但输出仍然是标准 JSON——双引号键、无尾逗号——因为 JSON 规范就只允许这些。
一次性看个响应、调试输出、内存里的临时值——这种场景用 JSON.stringify(data, null, 2) 或 FormatArc JSON 格式化器更快，不用装任何东西。Prettier 适合"整个代码库风格统一"，JSON.stringify 和浏览器工具适合"现在就要看到结果"。
终端里排版
jq
jq 是轻量级的命令行 JSON 处理器，管道进去就能出格式化结果：
echo '{"name":"Alice","age":30}' | jq .
Python 标准库
有 Python 的机器，json.tool 开箱即用：
echo '{"name":"Alice","age":30}' | python3 -m json.tool
curl 响应直接排版
调 API 时 curl 和 jq 组合最顺手：
curl -s https://api.example.com/data | jq .
浏览器里排版
FormatArc JSON 格式化器 全程在浏览器端运行，数据不会发往任何服务器。涉及 API key、内网配置、用户数据时，这点很重要。
用法
- 把要排版的 JSON 粘贴到输入框
- 点"格式化"按钮
- 复制结果
排版前先验证
JSON 有语法错误就排不了版。最常见的原因就是上面那几类：尾逗号、单引号、键没加引号。配置文件里想写注释的话，可以考虑 JSONC 或 JSON5 这类扩展格式。大文件里报错信息只给一个字符偏移量，找起来确实麻烦。
FormatArc 的格式化器会在出错时标出行号，方便快速定位。常见 parse 报错的原因与排查方法见JSON parse 报错排查。
Chrome 扩展自动排版
如果你经常直接在浏览器里打开 API 端点看原始响应，可以装 JSONView 或 JSON Formatter 这类 Chrome 扩展，让浏览器自动把 JSON 渲染成带缩进的树形视图，省掉手动粘贴到工具里的步骤。各扩展的差异与选型参考Chrome JSON 查看器扩展实测对比。
和其他数据格式的配合
JSON 排版经常不是孤立操作，而是转换流程里的一环：
- YAML 转 JSON：Kubernetes 配置、CI 流水线的 YAML 文件需要转成 JSON 时，用 FormatArc 的 YAML 转 JSON 工具
- CSV 转 JSON：电子表格导出的数据要变成 JSON 数组，用 FormatArc 的 CSV 转 JSON 工具
- JSON 转 CSV / 转 YAML：反过来也一样，一条管道的事
常见问题
JSON.stringify 的第三个参数能填什么？
JSON.stringify(value, replacer, space) 里，space 可以是 0 到 10 的整数（空格数），也可以是字符串（如 "\t" 表示 Tab）。实际项目中 2 空格最常见，兼顾可读性和文件体积。
带尾逗号或单引号的 JSON 能直接排版吗？
标准 JSON 解析器会直接报错。FormatArc 的 JSON 格式化器有"自动修复"选项，可以自动识别并去掉尾逗号、把单引号换成双引号，然后再做标准排版。
没有 jq 也没有 Python，终端怎么快速排版？
Node.js 环境：
node -e 'console.log(JSON.stringify(JSON.parse(require("fs").readFileSync(0,"utf8")),null,2))'
或者直接贴到 FormatArc JSON 格式化器，浏览器里几秒搞定。
贴到 FormatArc 的数据会发到服务器吗？
不会。FormatArc 所有转换和排版逻辑都在你的浏览器里（WebAssembly / JavaScript）完成，数据不出本机。API token、密钥这类敏感内容也可以放心贴。
总结
- JSON 排版（美化）是开发调试的日常操作，核心就是加缩进和换行
- 代码里：
JSON.stringify(data, null, 2)一行搞定 - 终端里：
jq .或python3 -m json.tool - 浏览器里：FormatArc JSON 格式化器，免安装、数据不出本机
- 最常见的语法错误：尾逗号、单引号、键没加引号