JavaScript中JSON.stringify怎么实现格式化输出

作者：桌面漫游

时间：2026-10-30

深入讲解JavaScript中JSON.stringify实现JSON数据格式化输出的完整方法。详解第三个参数space的数值与字符串规则、第二个参数replacer的过滤技巧、toJSON钩子机制及常见避坑注意事项。

文章目录

核心答案：在 JavaScript 中实现 JSON 格式化输出，关键在于向 JSON.stringify() 传入第三个参数 space。通常使用 JSON.stringify(data, null, 2) 即可自动插入换行符并以 2 个空格进行层级缩进；将 space 设为制表符 '\t' 或其他指定字符也能获得优雅对齐的可读文本。

一、核心语法与快速实现

默认情况下，JSON.stringify(value) 会将 JavaScript 对象压缩为单行无多余空格的字符串。这种紧凑模式适合网络数据传输以节省带宽，但在本地调试、排查日志或导出配置文件时，密集的单行文本极难阅读。

其实，JSON.stringify() 原生支持三个参数：

JSON.stringify(value, replacer, space)

value：待序列化的 JavaScript 对象、数组或基础类型数据。
replacer（可选）：转换器函数或键名白名单数组。若不需要过滤，必须显式传入 null 占位。
space（可选）：缩进控制器。可传入整数或字符串，用于指定每一层嵌套的缩进间距与换行规则。

最常用的格式化示例代码如下：

const user = {
  id: 1001,
  name: "张三",
  roles: ["developer", "reviewer"],
  profile: { department: "技术部", city: "北京" }
};

// 默认单行紧凑输出
console.log(JSON.stringify(user));
// 输出: {"id":1001,"name":"张三","roles":["developer","reviewer"],"profile":{"department":"技术部","city":"北京"}}

// 2个空格缩进格式化输出
console.log(JSON.stringify(user, null, 2));

调用上述带有第三个参数的语句后，控制台将输出层级分明的结构化文本：

{
  "id": 1001,
  "name": "张三",
  "roles": [
    "developer",
    "reviewer"
  ],
  "profile": {
    "department": "技术部",
    "city": "北京"
  }
}

JavaScript中JSON.stringify怎么实现格式化输出 — 图 1：JSON.stringify 参数结构与格式化处理流程

二、深入掌握 space 参数的规则与效果

space 参数决定了最终输出文本的排版外观。ECMAScript 规范对该参数的设计非常灵活，既支持直接传入数字指定空格数，也支持传入字符序列作为自定义前缀。

1. 传入正整数（空格缩进）

当传入一个正整数时，表示每一层对象或数组嵌套所增加的空格数量。例如：

JSON.stringify(data, null, 2)：每级缩进 2 个空格，这是现代前端工程与配置文件中最主流的风格，紧凑且可读。
JSON.stringify(data, null, 4)：每级缩进 4 个空格，结构对比更鲜明，常见于传统后端系统或控制台深层查看。

边界保护机制：如果传入的数值大于 10，引擎会自动将其截断为 10；如果传入小于 1 的数字或 0，则会被视作不开启格式化，依然输出紧凑单行。

2. 传入字符串（制表符或自定义前缀）

当传入一个非空字符串时，引擎会直接使用该字符串作为每一级的缩进符号：

JSON.stringify(data, null, '\t')：使用 Tab 制表符缩进，方便读者在编辑器中根据个人偏好自定义缩进宽度。
JSON.stringify(data, null, '··')：使用特定可见符号充当视觉对齐参考点。

如果传入的字符串长度超过 10 个字符，引擎只会截取前 10 个字符作为缩进单元。

三、搭配 replacer 参数：在格式化的同时清洗数据

在实际开发中，格式化输出往往伴随着敏感字段脱敏或无用字段剥离。利用第二个参数 replacer，我们可以在格式化排版之前对数据进行精准修剪。

1. 数组白名单过滤

当传入一个字符串或数字数组时，序列化过程将仅保留该数组中声明的属性名：

const sensitiveData = {
  id: 101,
  token: "secret_xyz_9988",
  username: "alice",
  email: "alice@example.com",
  passwordHash: "e10adc3949ba59abbe56e057f20f883e"
};

// 仅格式化保留 id、username 与 email 字段
const result = JSON.stringify(sensitiveData, ["id", "username", "email"], 2);
console.log(result);

输出结果如下，敏感字段被自动剔除，且保持良好的缩进结构：

{
  "id": 101,
  "username": "alice",
  "email": "alice@example.com"
}

2. 函数自定义映射与脱敏

当传入一个函数 (key, value) => modifiedValue 时，序列化器会深度递归遍历每个键值对：

首次调用时，key 为空字符串 ""，value 为顶层包裹对象。
返回具体值时，该值将作为对应属性的新值参与格式化。
返回 undefined 时，该属性将在序列化结果中被完全忽略。

const formattedReport = JSON.stringify(sensitiveData, (key, value) => {
  // 过滤掉密码哈希
  if (key === "passwordHash") return undefined;
  // 对 token 进行掩码处理
  if (key === "token" && typeof value === "string") {
    return value.slice(0, 4) + "****";
  }
  return value;
}, 2);

console.log(formattedReport);

3. 对象的 toJSON() 钩子方法

如果目标对象内部定义了 toJSON() 方法，JSON.stringify() 会首先调用该方法并序列化其返回值，随后再执行 replacer 和 space 排版流程。内置的 Date 对象正是通过该机制将自身自动转换为标准的 UTC ISO 字符串。

四、常见易错陷阱与实际工程应用

掌握了基本排版参数后，在实际工程（如 Node.js 配置文件读写、前端控制台排查、网络请求捕获）中还需要注意以下常见陷阱与性能边界。

1. 循环引用导致程序崩溃

如果对象属性间接或直接指向自身，JSON.stringify 会直接抛出错误：TypeError: Converting circular structure to JSON。可以通过在 replacer 中维护一个 WeakSet 来动态排查重复引用的对象：

function safeStringify(target, space = 2) {
  const seen = new WeakSet();
  return JSON.stringify(target, (key, value) => {
    if (typeof value === "object" && value !== null) {
      if (seen.has(value)) {
        return "[Circular Reference]"; // 替换循环标记，防止崩溃
      }
      seen.add(value);
    }
    return value;
  }, space);
}

const nodeA = { name: "节点A" };
const nodeB = { name: "节点B", ref: nodeA };
nodeA.cycle = nodeB; // 构造相互引用

console.log(safeStringify(nodeA, 2));

2. 特殊数据类型的隐式转换与丢失

数据类型	在普通对象中的序列化表现	在数组中的序列化表现
`undefined`	整条键值对直接被忽略丢失	转换为 `null`
`Function`	整条键值对直接被忽略丢失	转换为 `null`
`Symbol`	整条键值对直接被忽略丢失	转换为 `null`
`NaN` / `Infinity`	转换为 `null`	转换为 `null`
`Date` 实例	自动调用 toJSON() 输出 ISO 字符串	同左，输出 ISO 字符串
`BigInt`	抛出 TypeError 异常	抛出 TypeError 异常

3. 文件写入场景（Node.js 示例）

在 Node.js 中生成可人工编辑的配置文件（如 config.json）时，一定要显式传入缩进参数，并在末尾追加一个换行符，以符合标准 POSIX 文本文件规范：

import fs from "fs";

const projectConfig = {
  appName: "data-service",
  version: "1.2.0",
  port: 8080,
  features: { metrics: true, debugLog: false }
};

// 格式化输出写入文件，末尾追加换行符 \n
fs.writeFileSync(
  "config.json",
  JSON.stringify(projectConfig, null, 2) + "\n",
  "utf-8"
);

4. 生产环境传输的性能与带宽考量

格式化虽然极大提升了阅读体验，但也注入了大量的换行符（\n）和空格字符。对于包含数千条记录的复杂 JSON 数据，启用 space = 2 会导致文本体积增加 30% 到 60% 以上。因此：

网络通信传输：必须使用默认无缩进紧凑模式 JSON.stringify(data)。
生产日志收集：推荐紧凑单行格式，方便日志收集工具（如 Fluentd、ELK）按行解析。
本地调试与配置文件：使用 JSON.stringify(data, null, 2)，兼顾美观与工程严谨性。

五、总结与速查清单

在 JavaScript 中实现 JSON 格式化输出只需记住以下关键要点：

核心三参数：JSON.stringify(value, replacer, space)。
快速美化公式：JSON.stringify(data, null, 2) 是绝大多数开发场景的首选，使用 null 略过过滤，使用 2 保持适度的缩进排版。
参数约束：space 为数字时最大有效值为 10，为字符串时最多截取前 10 个字符。
清洗与格式化结合：需要过滤或脱敏时，第二个参数传入属性名数组或处理函数。
场景权衡：网络通信和高频生产日志保持无缩进紧凑格式，仅在本地调试和生成配置文件时使用缩进美化。