JS怎么使用JSON.stringify格式化JSON字符串并控制缩进

作者:开源拾贝时间:2026-11-18 09:05:50浏览:389

详细讲解JavaScript中如何利用JSON.stringify的第三个参数space格式化JSON字符串并精准控制缩进,涵盖数字缩进、制表符缩进、replacer字段过滤及常见边界问题。

JavaScript 数据序列化指南

在 JavaScript 中将对象转化为格式化、可读性高的 JSON 字符串,直接使用 JSON.stringify(value, replacer, space) 的第三个参数 space 即可完成。只要向该参数传入代表空格数量的数字(如 2 或 4)或指定缩进字符(如制表符 ' '),序列化引擎就会自动在层级嵌套处插入换行符与对应缩进,无需编写复杂的正则或递归函数。

JS怎么使用JSON.stringify格式化JSON字符串并控制缩进
图 0:紧凑单行 JSON 转换为带缩进层级结构的直观对照

一、认识 JSON.stringify 的完整参数结构

日常开发中,许多初学者习惯仅调用 JSON.stringify(data),因而容易产生一种直觉印象,认为该方法只接收一个参数,若要美化输出就必须引入第三方库。这种认识在只做简单网络数据提交时能够正常工作,但并没有完整利用原生 API 的能力。

ECMAScript 规范中,JSON.stringify 定义了三个形参:

  • value(必需):将被序列化为 JSON 字符串的 JavaScript 原始值、对象或数组。
  • replacer(可选):转换函数或属性白名单数组,用于过滤或修改属性转换规则;若不需要过滤,必须占位传入 null 或 undefined 才能访问第三参数。
  • space(可选):指定缩进格式与空白占位符。只要提供了该参数,输出的 JSON 就会由默认的“紧凑单行”切换为“分行排版”。
JS怎么使用JSON.stringify格式化JSON字符串并控制缩进
图 1:JSON.stringify 三参数定义与底层执行管道架构

以下代码演示了不传缩进参数与传入缩进参数时的基础对比:

示例代码:基础调用与缩进调用
// 准备一个包含嵌套结构的用户信息对象
const user = {
  id: 1001,
  nickname: "晨曦",
  roles: ["developer", "reviewer"],
  profile: {
    city: "杭州",
    active: true
  }
};

// 1. 常规单行序列化
const compactStr = JSON.stringify(user);

// 2. 传入缩进参数 2(第二参数占位传 null)
const formattedStr = JSON.stringify(user, null, 2);
输出结果示例(compactStr):
{"id":1001,"nickname":"晨曦","roles":["developer","reviewer"],"profile":{"city":"杭州","active":true}}
输出结果示例(formattedStr):
{ "id": 1001, "nickname": "晨曦", "roles": [ "developer", "reviewer" ], "profile": { "city": "杭州", "active": true } }

二、控制缩进的核心:第三参数 space 的取值规则

第三参数 space 决定了在每一个键值对及数组元素前插入什么前缀,以及在对象和数组闭合处如何缩进。它主要支持两种形式:数值和字符串。

1. 传入数字:指定每级缩进的空格数

当传入正整数时,每个嵌套层级都会在换行后填充对应数量的英文半角空格。

  • 常用推荐值(2 或 4):2 是目前前端工程中配置文件和调试日志最常用的缩进尺度,视觉紧凑且不易导致多层嵌套时水平溢出;4 则在传统后端或独立排版文档中更清晰。
  • 有效范围与截断机制:规范支持 1 到 10 之间的整数。如果传入的数值大于 10,引擎会自动截断为 10,不会无上限延展;如果传入小于 1 的数值(例如 0 或负数),则会被视为无缩进,依然输出紧凑单行。

2. 传入字符串:自定义每级前缀字符

当传入字符串时,该字符串将被直接作为每一级缩进的填充单位:

  • 使用制表符 ' ':对于希望缩进宽度跟随阅读者本地编辑器设置(如 2 空格宽或 4 空格宽)的场景,传入 ' ' 是理想方案。
  • 长度截断规则:如果传入的自定义字符串长度超过 10 个字符,规范规定仅提取前 10 个字符作为单层缩进前缀。
JS怎么使用JSON.stringify格式化JSON字符串并控制缩进
图 2:space 参数取 0、2、4 及制表符时的结构展示与规范约束
示例代码:测试不同 space 取值的实际表现
const sample = { project: "Antigravity", tags: ["tool", "ai"] };

// 1. 使用制表符 Tab 缩进
const tabIndent = JSON.stringify(sample, null, '	');

// 2. 超出上限:传入 20,实际按 10 个空格处理
const maxIndent = JSON.stringify(sample, null, 20);

// 3. 传入装饰性前缀(通常用于特殊标记,实际项目中推荐标准空格或Tab)
const markIndent = JSON.stringify(sample, null, '-- ');
输出结果示例(markIndent):
{ -- "project": "Antigravity", -- "tags": [ -- -- "tool", -- -- "ai" -- ] }

三、结合第二参数 replacer 实现字段过滤与排版联动

在很多实际排查场景下,开发者既需要格式化输出,又希望剔除对象中长篇大论的无用字段或敏感数据(如密码、Token)。此时第二参数 replacer 可以与 space 完美配合。

JS怎么使用JSON.stringify格式化JSON字符串并控制缩进
图 3:数据清洗与格式化排版的完整协同处理步骤

方式一:数组白名单筛选

如果传入一个由字符串或数字组成的数组,序列化过程将严格仅保留数组中列出的属性名,其它未声明的属性将被自动舍弃:

示例代码:使用白名单数组配合格式化
const account = {
  uid: 8848,
  username: "developer_01",
  passwordHash: "e10adc3949ba59abbe56e057f20f883e",
  loginIp: "192.168.1.100",
  createdAt: "2026-11-16"
};

// 仅保留 uid 和 username,并以 2 空格格式化
const safeLog = JSON.stringify(account, ["uid", "username"], 2);
输出结果示例:
{ "uid": 8848, "username": "developer_01" }

方式二:函数级动态转换与脱敏

如果传入转换函数 (key, value) => transformedValue,引擎在访问每个键值对时都会触发该函数。函数返回 undefined 时该属性会被忽略,返回其他值则替换原值:

示例代码:函数拦截脱敏并缩进输出
const sensitivePayload = {
  service: "auth",
  secretKey: "sk-9923847293",
  retryLimit: 3
};

const sanitizedStr = JSON.stringify(sensitivePayload, (key, value) => {
  if (key === "secretKey") {
    return "***HIDDEN***"; // 动态脱敏
  }
  return value; // 其余字段原样保留
}, 2);

四、认知辨析与常见边界场景

在实际使用格式化功能时,有几个关键概念和边界特性容易引发困惑,需要明确其成立条件与适用范围。

1. “格式化后的 JSON 字符串是否适合网络传输?”

辨析:有部分观点认为格式化后的字符串结构直观,便于排查,因此可以直接作为接口响应体。这种说法在开发环境联调时看似方便,但在生产网络传输中并不成立。

缩进与换行本质上都是 ASCII 字符( 占用 1 字节,每层 2 到 4 个空格占用 2 到 4 字节)。对于一个包含成百上千条记录的数据包,格式化后体积往往膨胀 30% 到 70%,白白消耗带宽与客户端解析开销。因此,网络 API 响应必须保持无 space 的单行紧凑模式,格式化仅应当用于本地日志打印、调试输出或构建本地 JSON 配置文件。

JS怎么使用JSON.stringify格式化JSON字符串并控制缩进
图 4:格式化选型决策矩阵与三大常见边界排查

2. 特殊数据类型引发的字段“失踪”

在格式化查看对象时,如果发现某些字段凭空消失,通常不是缩进参数引起的,而是由于 JSON 规范对数据类型的限制:

  • 对象属性值如果为 undefined、Function 或 Symbol,在序列化时会被直接忽略(属性键与值均不出现在输出中)。
  • 数组项如果为上述三类值,为了维持数组索引对应的位置关系,会被转换为 null。
  • NaN 和 Infinity 会被转为 null。

3. 循环引用报错(Circular Structure)

当待格式化的对象存在自引用或双向嵌套引用时,执行 JSON.stringify 会抛出运行时异常:TypeError: Converting circular structure to JSON。

排查方案:在格式化未知来源的复杂 DOM 节点或相互引用的复杂类实例前,应先通过 Set/WeakSet 做环检测,或者提取纯数据 DTO 对象后再执行格式化输出。

五、实用场景代码模板与速查表

场景 1:在 Node.js 中生成整齐的本地 JSON 配置文件

生成 config.json 或维护 package.json 时,必须使用带缩进的字符串写入,以保证版本管理(Git)能生成清晰的逐行 Diff:

示例代码:Node.js 写入配置文件
import fs from 'fs';

const projectConfig = {
  name: "service-gateway",
  version: "1.0.0",
  port: 8080,
  features: ["cors", "rate-limit"]
};

// 使用 2 空格缩进并末尾追加换行符,符合标准文件格式
const content = JSON.stringify(projectConfig, null, 2) + '\n';
fs.writeFileSync('./config.json', content, 'utf-8');

场景 2:在前端网页的 <pre><code> 中展示代码块

要在 HTML 页面上展示易于阅读的 JSON 数据包,直接输出到页面即可保持排版:

示例代码:DOM 渲染展示
const apiResponse = { status: 200, message: "OK", itemsCount: 42 };
const preElement = document.getElementById("json-viewer");

// 通过 textContent 注入,避免 HTML 实体注入风险
preElement.textContent = JSON.stringify(apiResponse, null, 2);

参数行为快速对照表

参数调用写法 输出形态 典型适用场景
JSON.stringify(obj) 无换行、无额外空格的紧凑单行 HTTP 请求与响应传输、数据持久化存储
JSON.stringify(obj, null, 2) 换行排版,每层缩进 2 个空格 浏览器控制台输出、终端 CLI 日志调试
JSON.stringify(obj, null, 4) 换行排版,每层缩进 4 个空格 清晰文档展示、项目本地 JSON 配置文件保存
JSON.stringify(obj, null, ' ') 换行排版,每层使用 1 个 Tab 缩进 依赖查看者本地编辑器自定义 Tab 宽度的文件生成
JSON.stringify(obj, filterArr, 2) 按白名单剔除无关字段并带 2 格缩进 敏感数据脱敏打印、精简关键业务对象调试
作者最新文章
相关文章
更多