How to Format JSON: Methods, Tools & Best Practices

为什么格式化 JSON 很重要

未格式化的 JSON 在技术上是有效的，但对人类来说却很不友好。在调试会话中，一行嵌套对象和数组的代码几乎无法扫描，这使得代码审查变成了猜谜游戏。

正确格式化的 JSON 给你带来三个直接的好处：可读性 — 你可以直观地追踪键值的层次结构；可调试性 — 差异工具和错误消息引用的行号实际上有意义；以及 协作 — 团队成员在审查你的 API 响应文件或配置文件时可以一目了然。

格式化还可以防止微妙的错误。当 JSON 被压缩时，很容易错过一个放错位置的括号或重复的键。展开结构使这些问题显而易见。

JSON 格式化的规则

在使用工具之前，了解“格式化 JSON”实际上意味着什么是很有帮助的。JSON 规范 (RFC 8259) 并不强制任何空白规则 — 格式化纯粹是一个展示问题。也就是说，社区已经达成了明确的约定：

• 每个键值对占据自己的一行。
• 嵌套对象和数组的缩进比其父级深一个级别。
• 冒号后跟一个空格：“key”: “value”。
• 逗号出现在每行的末尾（而不是开头）。
• 开括号和开方括号与键在同一行；闭括号与父级缩进级别对齐。

这是一个最小的示例。这个压缩的 JSON：

{"name":"Alice","age":30,"roles":["admin","editor"],"address":{"city":"Portland","state":"OR"}}

在使用 2 空格缩进格式化后变为：

{
  "name": "Alice",
  "age": 30,
  "roles": [
    "admin",
    "editor"
  ],
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}

格式化 JSON 的 3 种方法

每种方法都可以归入三类：在线工具、命令行工具或在应用程序代码中进行编程格式化。正确的选择取决于你在工作流程中的位置以及你需要执行此操作的频率。

1. 在线工具

基于浏览器的格式化工具是你只需一次性美化负载的最快路径 — 粘贴它，点击一个按钮，复制结果。无需安装任何东西，也无需切换到终端。

在线工具适合快速调试、与非技术利益相关者共享格式化片段，或在你无法安装软件的机器上使用。缺点是它们无法集成到自动化管道中。

自己试试： 将任何 JSON 粘贴到我们的 JSON Formatter 中，立即使用你选择的缩进进行美化。

2. 命令行工具

如果你习惯使用终端，两个命令几乎涵盖了所有格式化需求：

Python 的内置 json.tool 模块 — 在任何安装了 Python 的机器上可用，无需额外的包：

echo '{"name":"Alice","age":30}' | python -m json.tool

这将以良好的缩进输出 JSON 到标准输出。你也可以轻松地通过它管道传递文件：

python -m json.tool data.json > data-formatted.json

jq — 一个轻量级、专门构建的 JSON 处理器。最简单的格式化命令就是身份过滤器：

cat data.json | jq '.'

jq 在大多数终端中还添加了语法高亮，并且你可以链式过滤器以在一次传递中转换和格式化。这是处理 JSON 的 shell 脚本的首选。

这两个命令都可以链入 CI 管道。例如，你可以在预提交钩子中运行 jq --sort-keys . 来确保仓库中的所有 JSON 配置文件格式一致。

3. 编程格式化

当你编写应用程序代码时，在大多数语言中格式化 JSON 只需一行代码。

JavaScript / TypeScript:

const formatted = JSON.stringify(data, null, 2);

JSON.stringify 的第三个参数控制缩进。传入 2 表示 2 个空格，4 表示 4 个空格，或 "\t" 表示制表符。

Python:

import json

formatted = json.dumps(data, indent=2, ensure_ascii=False)

Go:

formatted, err := json.MarshalIndent(data, "", "  ")

编程格式化在生成 JSON 作为应用程序的一部分时至关重要 — 编写配置文件、创建 API 响应文件或生成文档。你完全控制输出。

比较格式化方法

以下是一个快速参考，帮助你为特定情况选择合适的方法：

标准	在线工具	CLI (jq / json.tool)	编程格式化
使用难易度	粘贴并点击	一行命令	需要代码上下文
一次性任务的速度	最快	快速	较慢（需要脚本）
自动化 / CI	不适合	优秀	优秀
自定义	有限	中等（标志）	完全控制
离线工作	否	是	是
处理大文件	浏览器限制	流式处理良好	取决于实现

缩进争论：2 空格 vs 4 空格 vs 制表符

这是一个产生更多争论而非光明的辩论，但每个选项都有实际原因。

2 空格

在 JSON 中最常见的选择。它保持深度嵌套结构紧凑，同时仍提供清晰的视觉层次。大多数 JavaScript 生态系统工具（ESLint、Prettier、npm 的 package.json）默认使用 2 空格。如果你正在处理 Web API 或 Node.js 项目，这是安全的默认选择。

4 空格

在 Python 相关的工作流和一些企业 Java 商店中流行。额外的宽度使嵌套级别更加明显，这在阅读大型配置文件时可能会有所帮助。缺点是深度嵌套的 JSON 很快会推向屏幕的右边缘。

制表符

制表符让每个开发人员可以在他们的编辑器中设置自己的视觉宽度。这在理论上听起来理想，但在实践中，大多数 JSON 工具和代码检查器都期望使用空格。制表符在基于 Web 的差异查看器和 GitHub PR 中的呈现也不一致。

何时使用每种：

• 2 空格 — Web 项目、JavaScript/TypeScript 代码库、API 负载。社区标准。
• 4 空格 — Python 重的团队、大型配置文件，在清晰度胜过紧凑性时使用。
• 制表符 — 具有混合语言偏好和严格可访问性要求的单一代码库（制表符允许用户配置宽度）。

最重要的是在项目中保持一致性。选择一种并强制执行。

排序键

大多数格式化工具提供“排序键”选项，可以按字母顺序排列对象键。这不仅仅是外观上的 — 它对版本控制有实际好处。

当键被排序时，差异变得有意义。如果不排序，两个开发人员可能会以不同的顺序添加相同的键，从而产生嘈杂的差异，掩盖实际的更改。排序键完全消除了这一点。

排序键还使扫描大型配置文件变得更容易。如果你知道要查找的键，可以跳到其字母位置而无需搜索。

唯一的警告是：某些 JSON 文件有意的键顺序（例如，package.json 中 name 和 version 按约定排在前面）。在这些情况下，保留原始顺序。

在 jq 中，使用以下命令排序键：

jq --sort-keys '.' data.json

在 JavaScript 中，传递一个替换函数或使用像 json-stable-stringify 这样的库以获得确定性的键顺序。

在 VS Code 中保存时自动格式化

最佳的格式化是你从未考虑过的那种。VS Code 可以在每次保存时自动格式化 JSON 文件。以下是设置方法：

步骤 1： 打开你的设置（macOS 上为 Cmd+,，Windows/Linux 上为 Ctrl+,），并添加以下条目：

{
  "editor.formatOnSave": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  }
}

步骤 2： 如果尚未安装 Prettier - Code formatter 扩展，请安装。它处理 JSON 格式化以及项目中的其他所有语言。

步骤 3： 在项目根目录创建一个 .prettierrc 文件，以标准化团队的设置：

{
  "tabWidth": 2,
  "useTabs": false
}

现在项目中的每个 JSON 文件都将以相同的方式格式化，无论是谁编辑的。再也不会在拉取请求中出现仅格式化的差异。

处理边缘情况

大多数格式化工具可以毫无问题地处理标准 JSON，但有一些情况可能会让你感到困扰：

• 大数字 — JSON 不区分整数和浮点数。一些格式化工具可能会将 1.0 重新格式化为 1，或在非常大的整数上失去精度。如果精度很重要，请验证输出。
• Unicode 转义 — 格式化工具可能会将 \u00e9 转换为字面字符 é 或反之亦然。两者都是有效的 JSON，但更改可能会导致意外的差异。
• 空对象和数组 — 一些格式化工具将 {} 展开为多行。其他工具保持它们紧凑。这是风格偏好，但要注意不同工具之间可能会有所不同。
• 尾随换行 — POSIX 约定说文本文件应以换行结束。大多数格式化工具会添加一个，但并非所有工具都会。检查你的 .editorconfig 如果这对你的 CI 重要。

将格式化作为工作流程的一部分

最有效的团队将 JSON 格式化视为与代码格式化相同 — 作为开发过程中的自动化、不可协商的部分。

预提交钩子： 使用像 husky 和 lint-staged 这样的工具在每次提交之前对 JSON 文件运行 Prettier 或 jq。这可以在它们进入代码库之前捕获格式化问题。

CI 检查： 在你的 CI 管道中添加一个格式化检查，如果任何 JSON 文件未正确格式化，则失败。Prettier 有一个 --check 标志，正是为了这个目的。

编辑器集成： 保存时格式化完全消除了手动格式化。结合共享配置文件，它确保每个团队成员生成相同的输出。

目标是使格式化变得无形 — 这是自动发生的事情，以便开发人员可以专注于 JSON 文件的实际内容，而不是它们的外观。

自己试试： 将未格式化的 JSON 粘贴到我们的 JSON Formatter 中，立即进行美化。你还可以 验证你的 JSON 以在格式化之前捕获结构错误。