如何格式化 JSON：最佳实践和工具

# 如何格式化 JSON：最佳实践和工具

正确格式化 JSON 对于可读性和调试至关重要。无论您是处理 API 响应、配置文件还是数据导出，本综合指南将向您展示在 2026 年格式化和美化 JSON 的每种方法。

为什么要格式化 JSON？

可读性

压缩（难以阅读）：

{"name":"张三","age":30,"address":{"street":"北京市朝阳区建国路 123 号","city":"北京"},"hobbies":["阅读","编程"]}

格式化（易于阅读）：

{
  "name": "张三",
  "age": 30,
  "address": {
    "street": "北京市朝阳区建国路 123 号",
    "city": "北京"
  },
  "hobbies": [
    "阅读",
    "编程"
  ]
}

调试

格式化的 JSON 使以下操作更容易：

• 发现语法错误
• 识别缺失的逗号
• 验证数据结构
• 追踪问题

版本控制

正确格式化的 JSON 在 Git 中产生更清晰的差异。

方法 1：在线 JSON 格式化器

Big JSON Viewer

快速，处理大文件：

访问 Big JSON Viewer

粘贴或上传 JSON

点击"格式化"

复制格式化的结果

JSONLint

验证和格式化：

访问 jsonlint.com

粘贴 JSON

点击"验证 JSON"

获取格式化的输出

JSON Formatter

简单快速：

访问 jsonformatter.org

粘贴内容

自动立即格式化

方法 2：命令行工具

使用 jq

最强大的命令行 JSON 处理器：

# 格式化 JSON 文件
jq . input.json

# 格式化并保存
jq . input.json > formatted.json

# 使用 4 空格缩进格式化
jq --indent 4 . input.json

# 从 API 响应格式化
curl https://api.example.com/data | jq .

# 压缩（最小化）
jq -c . input.json

安装：

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Windows (Chocolatey)
choco install jq

# Windows (Scoop)
scoop install jq

使用 Python

Python 内置 JSON 格式化：

# 格式化 JSON 文件
python -m json.tool input.json

# 格式化并保存
python -m json.tool input.json > formatted.json

# 压缩 JSON
python -c "import json,sys; print(json.dumps(json.load(sys.stdin)))" < input.json

使用 Node.js

简单的 Node.js 脚本：

# 一行命令格式化
node -e "console.log(JSON.stringify(JSON.parse(require('fs').readFileSync('input.json')), null, 2))"

创建可重用的脚本：

// format.js
const fs = require('fs');
const json = JSON.parse(fs.readFileSync(process.argv[2]));
console.log(JSON.stringify(json, null, 2));

# 使用
node format.js input.json > formatted.json

方法 3：代码编辑器

Visual Studio Code

方法 1：快捷键

• Windows/Linux：Shift + Alt + F
• macOS：Shift + Option + F

方法 2：命令面板

按 Ctrl+Shift+P（或 Mac 上的 Cmd+Shift+P）

输入"Format Document"

按 Enter

方法 3：右键菜单

右键点击 JSON 文件

选择"格式化文档"

配置设置：

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

Sublime Text

使用包控制：

安装"Pretty JSON"插件

快捷键：Ctrl+Alt+J（Windows/Linux）或 Cmd+Ctrl+J（Mac）

手动方法：

选择 JSON 内容

工具 → 命令面板

输入"Pretty JSON: Format"

JetBrains IDE（WebStorm、IntelliJ）

快捷键：

• Windows/Linux：Ctrl + Alt + L
• macOS：Cmd + Option + L

配置：

设置 → 编辑器 → 代码样式 → JSON
缩进：2 空格
延续缩进：2 空格

Vim

使用 Python：

:%!python -m json.tool

使用 jq：

:%!jq .

添加到 .vimrc：

" 格式化 JSON
command! FormatJSON %!python -m json.tool

方法 4：编程语言

JavaScript/Node.js

// 格式化 JSON 字符串
const jsonString = '{"name":"张三","age":30}';
const formatted = JSON.stringify(JSON.parse(jsonString), null, 2);
console.log(formatted);

// 输出：
// {
//   "name": "张三",
//   "age": 30
// }

// 自定义缩进
const customIndent = JSON.stringify(obj, null, 4); // 4 空格
const tabIndent = JSON.stringify(obj, null, '	'); // 制表符

Python

import json

# 格式化 JSON 字符串
json_string = '{"name":"张三","age":30}'
parsed = json.loads(json_string)
formatted = json.dumps(parsed, indent=2, ensure_ascii=False)
print(formatted)

# 从文件格式化
with open('input.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

with open('output.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

# 自定义缩进
formatted = json.dumps(data, indent=4)  # 4 空格

PHP

<?php
// 格式化 JSON 字符串
$jsonString = '{"name":"张三","age":30}';
$data = json_decode($jsonString);
$formatted = json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
echo $formatted;

// 从文件格式化
$data = json_decode(file_get_contents('input.json'));
file_put_contents(
    'output.json', 
    json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE)
);
?>

Java

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonParser;

public class JsonFormatter {
    public static void main(String[] args) {
        String json = "{"name":"张三","age":30}";

        Gson gson = new GsonBuilder()
            .setPrettyPrinting()
            .create();

        Object parsed = JsonParser.parseString(json);
        String formatted = gson.toJson(parsed);
        System.out.println(formatted);
    }
}

C#

using System;
using System.Text.Json;

class Program
{
    static void Main()
    {
        string json = "{"name":"张三","age":30}";

        var options = new JsonSerializerOptions 
        { 
            WriteIndented = true,
            Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping
        };

        var document = JsonDocument.Parse(json);
        string formatted = JsonSerializer.Serialize(document, options);
        Console.WriteLine(formatted);
    }
}

Go

package main

import (
    "encoding/json"
    "fmt"
    "log"
)

func main() {
    jsonString := {"name":"张三","age":30}

    var data interface{}
    if err := json.Unmarshal([]byte(jsonString), &data); err != nil {
        log.Fatal(err)
    }

    formatted, err := json.MarshalIndent(data, "", "  ")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(string(formatted))
}

方法 5：浏览器开发者工具

Chrome DevTools

打开开发者工具（F12）

转到"Console"

粘贴：

copy(JSON.stringify(JSON.parse('你的JSON字符串'), null, 2))

格式化的 JSON 现在在剪贴板中

Firefox

打开开发者工具（F12）

转到"Console"

输入：

JSON.stringify(JSON.parse('你的JSON'), null, 2)

高级格式化技术

自定义替换器

const data = {
  name: "张三",
  password: "secret123",
  age: 30
};

// 过滤敏感数据
const filtered = JSON.stringify(data, (key, value) => {
  if (key === 'password') return undefined;
  return value;
}, 2);

console.log(filtered);
// {
//   "name": "张三",
//   "age": 30
// }

排序键

function sortedStringify(obj, space) {
  const allKeys = new Set();
  JSON.stringify(obj, (key, value) => {
    allKeys.add(key);
    return value;
  });

  return JSON.stringify(obj, Array.from(allKeys).sort(), space);
}

const data = { z: 1, a: 2, m: 3 };
console.log(sortedStringify(data, 2));
// {
//   "a": 2,
//   "m": 3,
//   "z": 1
// }

颜色输出（终端）

const chalk = require('chalk');

function colorJSON(obj) {
  return JSON.stringify(obj, null, 2)
    .replace(/"([^"]+)":/g, chalk.blue('"$1"') + ':')
    .replace(/: "([^"]+)"/g, ': ' + chalk.green('"$1"'))
    .replace(/: (d+)/g, ': ' + chalk.yellow('$1'))
    .replace(/: (true|false)/g, ': ' + chalk.magenta('$1'));
}

console.log(colorJSON({ name: "张三", age: 30, active: true }));

格式化选项

缩进样式

2 空格（推荐）：

{
  "name": "张三",
  "age": 30
}

4 空格：

{
    "name": "张三",
    "age": 30
}

制表符：

{
	"name": "张三",
	"age": 30
}

数组格式化

内联（短数组）：

{
  "colors": ["红", "绿", "蓝"]
}

多行（长数组）：

{
  "users": [
    {"id": 1, "name": "张三"},
    {"id": 2, "name": "李四"},
    {"id": 3, "name": "王五"}
  ]
}

压缩与美化

美化（开发）：

{
  "name": "MyApp",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0"
  }
}

压缩（生产）：

{"name":"MyApp","version":"1.0.0","dependencies":{"express":"^4.18.0"}}

自动化格式化

Git 钩子

pre-commit 钩子：

#!/bin/bash
# .git/hooks/pre-commit

# 格式化所有暂存的 JSON 文件
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '.json$'); do
  jq . "$file" > "$file.tmp" && mv "$file.tmp" "$file"
  git add "$file"
done

Prettier

安装：

npm install --save-dev prettier

配置（.prettierrc）：

{
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false
}

使用：

# 格式化所有 JSON
npx prettier --write "*/.json"

# 格式化特定文件
npx prettier --write data.json

ESLint

配置：

{
  "extends": ["plugin:json/recommended"],
  "plugins": ["json"],
  "rules": {
    "json/*": ["error", {"allowComments": false}]
  }
}

常见格式化错误

1. 尾随逗号

❌ 错误：

{
  "name": "张三",
  "age": 30,
}

✅ 正确：

{
  "name": "张三",
  "age": 30
}

2. 单引号

❌ 错误：

{
  'name': '张三'
}

✅ 正确：

{
  "name": "张三"
}

3. 注释

❌ 错误：

{
  // 这是注释
  "name": "张三"
}

✅ 正确：

{
  "name": "张三"
}

4. 不一致的缩进

❌ 错误：

{
  "name": "张三",
    "age": 30,
  "city": "北京"
}

✅ 正确：

{
  "name": "张三",
  "age": 30,
  "city": "北京"
}

最佳实践

1. 一致的缩进

在整个项目中使用 2 或 4 空格。

2. 开发时格式化

启用保存时自动格式化。

3. 生产前压缩

压缩 JSON 以减少文件大小。

4. 使用 Linter

自动捕获格式错误。

5. 版本控制

提交前格式化 JSON 文件。

6. 记录约定

在团队中共享格式标准。

性能考虑

大文件

对于大型 JSON 文件（>10MB）：

# 使用 jq 流式处理
jq -c . large.json | jq .

# 或使用专用工具
npm install -g json-bigint

内存使用

// 流式解析大文件
const fs = require('fs');
const { Transform } = require('stream');

const formatStream = new Transform({
  transform(chunk, encoding, callback) {
    // 处理块
    callback(null, chunk);
  }
});

fs.createReadStream('large.json')
  .pipe(formatStream)
  .pipe(fs.createWriteStream('formatted.json'));

工具比较

| 工具 | 速度 | 功能 | 易用性 | 最适合 |

|------|------|------|--------|--------|

| jq | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | CLI、自动化 |

| Python | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 脚本、简单任务 |

| VS Code | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 交互式编辑 |

| 在线工具 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 快速任务 |

| Prettier | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 项目标准 |

结论

格式化 JSON 是每个开发人员工作流程中的基本技能。无论您喜欢命令行工具、代码编辑器还是编程解决方案，都有适合每种情况的方法。

快速建议：

• 快速任务：使用在线格式化器
• 开发：VS Code + Prettier
• 自动化：jq 或 Python 脚本
• 大文件：jq 或流式处理
• 团队项目：Prettier + Git 钩子

通过掌握这些格式化技术，您将节省时间、减少错误，并保持整个项目的一致代码质量。