JS使用JSON.stringify实现格式化输出与缩进控制

在 JavaScript 中，将对象序列化为可读性强的格式化字符串，主要依赖 JSON.stringify(value, replacer, space) 的第三个参数 space。在默认情况下，该方法输出紧凑的单行文本，所有空格与换行均被省略；当传入正整数或指定填充字符串时，序列化器将自动在每个对象层级插入换行符与缩进字符。本文直接解析 space 参数的取值规则、缩进控制边界、与 replacer 的协同机制及实际开发中的关键避坑点。

一、核心参数解析与格式化触发机制

JSON.stringify() 方法最多可以接收三个参数。理解各参数的职责是实现精确格式化控制的前提：

JSON.stringify(value, replacer, space)

• value（必须）：待转换的 JavaScript 对象、数组或原始值。
• replacer（可选）：用于转换结果的函数或过滤键名的数组。若无需过滤但需设置缩进，必须显式传递 null 占位。
• space（可选）：控制美化输出的核心参数。可传入数字或字符串，用于指定每层缩进的空白字符或自定义前缀。

格式化行为由 space 的有效性决定：当 space 为 undefined、null、0、负数或空字符串时，引擎采用紧凑输出模式（Compact Mode），将整个对象拼接为连续单行文本；当 space 为有效正整数或非空字符串时，引擎开启美化输出模式（Pretty-print Mode），自动为对象属性与数组元素添加换行符 并按递归深度注入缩进。

二、缩进控制的具体实现方式与代码示例

在实际编码中，控制缩进主要分为“按空格数缩进”与“按指定字符缩进”两种形式。二者在渲染效果、数据体积和跨平台适配性上存在差异。

1. 使用数字指定空格缩进（最常用）

向 space 传入正整数 n，表示每一层嵌套缩进 n 个半角空格。社区通常约定使用 2 或 4。

const userProfile = {
  name: "张三",
  role: "工程师",
  details: {
    department: "基础架构组",
    level: 3
  }
};

// 格式化输出：缩进 2 个空格
const formattedJson = JSON.stringify(userProfile, null, 2);
console.log(formattedJson);

{
  "name": "张三",
  "role": "工程师",
  "details": {
    "department": "基础架构组",
    "level": 3
  }
}

如果将参数修改为 4，缩进阶梯将加宽，适合行长度宽裕、嵌套层级浅的代码阅读场景：

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

{
    "name": "张三",
    "role": "工程师",
    "details": {
        "department": "基础架构组",
        "level": 3
    }
}

2. 使用制表符（ ）实现自适应缩进

如果希望缩进宽度跟随用户的编辑器设置或终端环境自动调整，可直接传入制表符字符串 ' '：

// 使用制表符作为缩进符
const tabFormattedJson = JSON.stringify(userProfile, null, '	');
console.log(tabFormattedJson);

{
	"name": "张三",
	"role": "工程师",
	"details": {
		"department": "基础架构组",
		"level": 3
	}
}

3. 使用自定义前缀字符（特殊排版与日志调试）

space 可以是任意字符串。该字符串将被原样重复填入每层缩进的前缀位置。例如在终端输出层级结构时使用 "· " 或 "-- " 强化层级感：

// 使用自定义字符增强层级视觉
console.log(JSON.stringify(userProfile, null, "· "));

{
· "name": "张三",
· "role": "工程师",
· "details": {
· · "department": "基础架构组",
· · "level": 3
· }
}

三、协同应用：结合 replacer 过滤与格式化

在实际应用中，单纯格式化往往不够，很多时候需要剔除敏感字段（如密码、内部密钥）或转换特定数据类型。replacer 参数与 space 参数协同工作，构成了一套先筛选转换、后排版缩进的完整流水线。

1. 使用数组作为白名单，提取并格式化指定属性

当 replacer 传入字符串或数字数组时，序列化过程将严格只保留数组中列出的属性名，其它字段自动忽略：

const sensitiveData = {
  id: 1001,
  username: "alex_dev",
  passwordHash: "8f4e2...a9",
  secretKey: "k8#99xL!",
  email: "alex@example.com"
};

// 仅保留 id、username 和 email，并按 2 空格格式化
const filteredJson = JSON.stringify(sensitiveData, ["id", "username", "email"], 2);
console.log(filteredJson);

{
  "id": 1001,
  "username": "alex_dev",
  "email": "alex@example.com"
}

2. 使用函数进行动态脱敏与值处理

当 replacer 是一个函数时，它会递归遍历对象的每个键值对 (key, value)。函数返回值将作为该键的最终序列化结果。返回 undefined 则表示删除该属性：

const orderInfo = {
  orderId: "ORD-2026-9901",
  amount: 288.5,
  apiKey: "sk-live-772199",
  createdAt: new Date("2026-11-10T14:30:00Z")
};

function maskSensitiveReplacer(key, value) {
  // 隐藏 API 密钥
  if (key === "apiKey") {
    return undefined; // 属性将被剔除
  }
  // 对金额统一格式化保留两位小数
  if (key === "amount" && typeof value === "number") {
    return `¥${value.toFixed(2)}`;
  }
  return value; // 其余字段原样输出
}

const safeFormattedJson = JSON.stringify(orderInfo, maskSensitiveReplacer, 2);
console.log(safeFormattedJson);

{
  "orderId": "ORD-2026-9901",
  "amount": "¥288.50",
  "createdAt": "2026-11-10T14:30:00.000Z"
}

四、边界条件与常见陷阱

虽然 JSON.stringify 接口使用直观，但在处理复杂业务对象或深层数据时，存在若干硬性边界和易忽视的行为机制：

1. 缩进长度的 10 字符上限

根据 ECMAScript 规范定义，space 参数的最大有效长度为 10。如果传入大于 10 的整数（例如 20），系统会自动将其截断为 10；如果传入超过 10 个字符的字符串（例如 "--------------------"），则仅截取前 10 个字符作为缩进前缀。

// 传入 20，实际缩进为 10 个空格
const overLimitNum = JSON.stringify({ a: 1 }, null, 20);

// 传入长字符串，仅保留前 10 个字符
const overLimitStr = JSON.stringify({ a: 1 }, null, "1234567890EXTRA");

2. 循环引用直接抛出异常

当序列化对象存在自引用或环状链条时，序列化过程无法计算终止深度，将直接抛出 TypeError: Converting circular structure to JSON。美化格式化不会对循环引用做容错保护：

const nodeA = { name: "节点A" };
const nodeB = { name: "节点B" };
nodeA.child = nodeB;
nodeB.parent = nodeA; // 构造循环引用

try {
  JSON.stringify(nodeA, null, 2);
} catch (err) {
  console.error("序列化失败：", err.message);
  // 输出：Converting circular structure to JSON
}

3. 特殊类型的值在序列化中的丢失

JSON 规范仅支持对象、数组、字符串、数字、布尔值与 null。当源对象包含其他 JavaScript 类型时：

• 对象属性中的特殊值：值为 undefined、函数（Function）或 Symbol 的属性，在序列化时会被直接忽略（属性键值对直接消失）。
• 数组项中的特殊值：位于数组中的 undefined、函数或 Symbol，会被转换为 null，以保持数组索引对应的位置稳定。
• NaN 与 Infinity：数值 NaN、Infinity 以及 -Infinity 会被自动强制转换为 null。
• BigInt 类型：直接对包含 BigInt 的对象执行 JSON.stringify 会直接抛出 TypeError: Do not know how to serialize a BigInt，需在 replacer 中将其转换为数字或字符串。

五、场景决策与核心速查

在工程实践中，是否启用格式化输出以及选择何种缩进策略，应依据运行环境与输出目标严格区分：

综上所述，通过合理运用 JSON.stringify 的第三个参数 space，开发者能够在无需引入第三方美化库的前提下，精确控制 JSON 文本的缩进深度与排版风格。结合第二参数 replacer 的筛选与转换能力，不仅能输出清晰易读的数据结构，更能保障运行时的安全性与数据严谨性。