JS怎么使用JSON.stringify实现JSON格式化与缩进

一、核心语法与第三个参数 space 的作用机制

标准 JavaScript 中的 JSON.stringify() 方法接收三个参数，其完整函数签名如下：

JSON.stringify(value, replacer, space)

当日常只传入一个参数 JSON.stringify(obj) 时，JavaScript 引擎会默认采用紧凑模式，剔除所有不必要的空格与换行符。这种格式虽然利于减少网络传输字节数，但在调试、控制台打印、日志记录或向网页前端展示数据时，可读性极差。

要让输出结果具备排版缩进，关键就在于第三个参数 space。space 决定了在每一个嵌套层级前插入的空格或字符，同时指示序列化引擎在键值对和数组项之间自动加入换行符 。

参数 space 的传值规则

参数 space 支持传入两种不同类型的值，对应不同的缩进渲染行为：

• 数字类型（Number）：传入大于等于 1 的整数，代表每一级缩进所包含的空格数量。例如传入 2 表示每层缩进 2 个空格，传入 4 表示每层缩进 4 个空格。根据 ECMAScript 规范，该数值的有效上限为 10，如果传入数值大于 10，引擎会自动将其截断为 10；如果传入小于 1 的数值，则等同于不启用缩进。
• 字符串类型（String）：传入指定字符串，每一级缩进都会直接使用该字符串作为前缀。例如传入制表符 ' '，即可生成按 Tab 缩进的 JSON；或者传入自定义前缀字符。若字符串长度超过 10，规范规定同样只取其前 10 个字符。

二、常用缩进模式对比：2 空格、4 空格与制表符（Tab）

在实际项目开发中，选择何种缩进方式并非随意决定。为了帮助开发者根据应用环境做出合理判断，我们在相同的数据对象条件下，对比三种主流缩进方案的关键差异与适用边界。

const userProfile = {
  id: 1024,
  username: "alex_dev",
  active: true,
  roles: ["developer", "reviewer"],
  profile: {
    department: "Frontend",
    level: "Senior"
  }
};

差异为什么重要：对于只有一两层嵌套的简单对象，2 空格与 4 空格的体验差距并不明显；但一旦数据包含四五层深度，4 空格会导致每一行向右偏移过大，在移动端界面或分屏终端中极易发生自动折行或截断，破坏对齐美感。因此在绝大多数 Web 前端开发与接口调试场景中，推荐优先选用 2 空格缩进（2）。

三、实战操作步骤：从原始数据到页面与终端呈现

在真实业务中，生成格式化 JSON 的完整过程通常包含四个连续环节：准备原始数据、执行序列化、指定目标呈现介质以及结果核验。

步骤 1：准备待序列化的 JavaScript 数据

确保目标数据结构为纯净的键值对象或数组，确认其内部没有包含循环引用结构。

const productData = {
  sku: "A-9872",
  title: "无线双模机械键盘",
  price: 299.00,
  inventory: {
    warehouse: "上海仓",
    quantity: 150
  },
  supportedOS: ["Windows", "macOS", "Linux"]
};

步骤 2：调用 JSON.stringify 传入格式化参数

执行序列化，传入数据对象、null 占位符及缩进空格数 2：

const formattedJson = JSON.stringify(productData, null, 2);

步骤 3：输出到控制台或渲染到 HTML 页面

在控制台输出：直接使用 console.log(formattedJson) 打印，开发者工具会完整保留每一行的换行与缩进空格。

在 HTML 网页中展示：普通 HTML 元素（如 <div>、<p>）在默认情况下会自动合并连续的空格并将换行符视作单个空格。为了在页面上完整还原格式化排版，必须将内容放入 <pre><code> 容器中，或者为元素指定 CSS 样式 white-space: pre-wrap;。

// 网页 DOM 注入示例
const codeElement = document.getElementById("json-viewer");
// 使用 textContent 赋值，避免 XSS 注入风险并保留纯文本排版
codeElement.textContent = formattedJson;

步骤 4：核验排版与数据完整性

查看输出文本的首尾大括号是否完整闭合，各层级的冒号与键值对是否按照 2 空格或 4 空格标准准确对齐。如果用于配置导出，可尝试用 JSON.parse(formattedJson) 回读一次，确保该格式化字符串是完全合法的 JSON。

四、进阶用法：结合 replacer 过滤与缩进协同

在格式化调试时，有时对象包含很多我们不关心的冗余字段，或者需要脱敏关键属性。此时，第二个参数 replacer 便能与第三个参数 space 完美协同工作。

1. 使用白名单数组过滤字段

如果只想查看对象中特定的几个属性，可以给 replacer 传入一个包含属性名字符串的数组：

const serverInfo = {
  host: "192.168.1.10",
  port: 8080,
  secretKey: "xyz-private-key",
  cluster: "prod-east",
  cpuUsage: "35%"
};

// 仅保留 host、port 和 cluster 三个字段进行格式化
const filteredJson = JSON.stringify(serverInfo, ["host", "port", "cluster"], 2);

2. 使用替换函数实现动态脱敏与转换

也可以传入一个函数 (key, value) => ...，在序列化排版的过程中动态对特定字段的值进行重写：

const maskedJson = JSON.stringify(serverInfo, (key, value) => {
  if (key === "secretKey") {
    return "******"; // 脱敏保密字段
  }
  return value;
}, 2);

五、关键规则与避坑要点

使用 JSON.stringify 进行格式化时，有四项底层机制与边界限制需要特别留意：

1. 特殊类型的静默丢失：如果对象的属性值为 undefined、函数（Function）或 Symbol，在 JSON.stringify 序列化过程中会被直接忽略，格式化后的字符串中将不会包含这些键；但若它们位于数组项中，则会被转为 null 占位，以保持数组索引对应。
2. 循环引用的致命报错：如果待格式化的对象存在循环引用（例如 a.self = a），JSON.stringify 会直接抛出未捕获的运行时异常：TypeError: Converting circular structure to JSON。在处理复杂 DOM 节点或图结构数据时，务必提前清洗或使用专用防循环引用工具函数。
3. 字符体积开销与网络传输边界：格式化输出会在原本紧密的字符串中插入成百上千个换行符 和空格符。对于包含大量数组的大型对象，体积可能膨胀 30% 到 80%。因此，格式化输出仅应用于开发调试、控制台打印、日志持久化查看或网页界面代码高亮展示，在客户端与服务端的正式 HTTP 接口请求传输中，始终应使用无缩进的单行模式。
4. 对象的 toJSON 拦截行为：如果对象中定义了 toJSON() 方法，JSON.stringify 会优先调用该方法，并将其返回值作为实际序列化内容。例如内置的 Date 对象包含 toJSON()，因此日期类型会被自动转为 UTC 格式的 ISO 8601 时间字符串。

六、全文总结

在 JavaScript 中使用 JSON.stringify 实现 JSON 格式化与缩进十分简洁高效，核心只要掌握 JSON.stringify(value, null, space) 的调用形态。日常开发中推荐将 space 设置为 2，在可读性与横向展示宽度之间取得平衡；在展示到网页时搭配 <pre> 容器或 white-space: pre-wrap;，即可完美呈现清晰易懂的树状数据。