怎么通过replacer函数自定义JS中JSON的格式化输出

在 JavaScript 中自定义 JSON 格式化输出，核心是使用 JSON.stringify(value, replacer, space) 的第二个参数 replacer。当传入一个自定义函数 function(key, value) 时，序列化引擎会以深度优先的方式递归遍历数据结构的每个节点；通过在该函数中针对不同的键值返回转换后的值、返回 undefined 过滤字段，或者把原生不支持的数据类型（如 BigInt、Set、Map）转换为标准格式，再配合第三个参数 space 提供缩进，即可精准实现结构清洗与格式化排版。

图 1：JSON.stringify 数据转换与 replacer 管道架构拓扑

一、replacer 函数的核心机制与调用规则

JSON.stringify 函数一共接受三个参数：首个参数为待序列化的目标数据，第二个参数即转换器 replacer，第三个参数为格式化缩进符号 space。虽然 replacer 也可以是一个仅包含允许导出的属性名数组，但函数形式提供了真正可编程的数据处理能力。

在调用 replacer(key, value) 时，JavaScript 引擎有三个非常关键的底层约定：

• 虚拟根节点首次调用：当引擎启动序列化时，它并不会直接从对象的第一个常规属性开始，而是先在最外层构造一个虚拟对象 { "": value }。因此，replacer 的首次调用传参是 key = ""，value 则是整个传入的目标对象。如果在此处直接对 key 做过滤且没有正确放行根对象，会导致序列化立刻中断并返回 undefined。
• 执行上下文与 this 绑定：当使用普通函数声明（非箭头函数）时，每次执行 replacer，函数体内部的 this 均指向当前属性所在的父对象容器。这意味着可以在处理子属性时，动态读取其兄弟属性或父级元信息。
• 深度优先递归处理（DFS）：如果 replacer 对某一个键返回的是一个普通对象或数组，引擎会立刻把这个返回值推入处理栈，继续深入遍历其内部的所有属性，直至所有叶子节点处理完毕。

二、replacer 的执行步骤与分支判定

编写 replacer 函数时，应遵循固定的处理阶段。标准步骤包括拦截虚拟根节点、获取当前节点上下文、计算转换逻辑，以及返回合适的目标值。

图 2：replacer 函数深度优先处理与分支判定执行步骤

在图 2 所示的阶段 03 中，序列化引擎会根据 replacer 的返回值类型采取不同的输出动作：

1. 返回 undefined、函数或 Symbol：如果当前正在处理的是一个普通对象的属性，返回 undefined 会使得该属性在最终 JSON 字符串中彻底被剔除；但如果当前处理的是数组中的某一项，返回 undefined 并不会缩小数组长度，而是会被序列化为 null，以此保证整个数组的索引顺序与原始结构一致。
2. 返回基础类型值（String、Number、Boolean、null）：该属性值会被直接作为最终输出，不产生进一步的递归。
3. 返回新对象或数组：引擎会以此新对象作为新的子树继续向下递归，对新对象的每个键再次调用 replacer。

三、典型应用场景与完整代码示例

图 3：数据类型处理与返回值行为转换矩阵

1. 敏感数据脱敏与多余字段过滤

在向前端接口返回数据或记录日志时，常常需要剔除密码、私钥，并对身份证号或手机号进行掩码保护。通过在 replacer 中对属性名进行判断，即可一次性完成过滤与清洗：

// 示例：敏感信息过滤与手机号脱敏
const userProfile = {
  id: 1001,
  username: "zhangsan",
  passwordHash: "e10adc3949ba59abbe56e057f20f883e",
  secretKey: "k-9921828",
  contact: {
    phone: "13800138000",
    email: "zhangsan@example.com"
  }
};

function maskSensitiveData(key, value) {
  // 必须放行根节点
  if (key === "") {
    return value;
  }

  // 1. 完全剔除敏感键
  if (key === "passwordHash" || key === "secretKey") {
    return undefined;
  }

  // 2. 对特定字段进行掩码处理
  if (key === "phone" && typeof value === "string") {
    return value.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2");
  }

  return value;
}

const outputJson = JSON.stringify(userProfile, maskSensitiveData, 2);
console.log(outputJson);

2. 解决 BigInt 与复杂集合类型无法序列化的问题

ECMAScript 标准规定，原生 JSON.stringify 遇到 BigInt 类型时会直接抛出 TypeError: Do not know how to serialize a BigInt。同时，Set 和 Map 默认会被序列化为普通的空对象 {}。借助 replacer 函数，可以安全地将这些类型转换为符合规范的通用格式：

// 示例：适配 BigInt、Set 与 Map 的序列化
const complexPayload = {
  orderId: 9007199254740993n, // 超出 Number 安全范围的 BigInt
  status: "PAID",
  tags: new Set(["vip", "fast-shipping"]),
  attributes: new Map([
    ["color", "metallic-blue"],
    ["warrantyYear", 2]
  ])
};

function typeAdapterReplacer(key, value) {
  if (key === "") return value;

  // 转换 BigInt 为字符串，避免抛出 TypeError 并防止精度丢失
  if (typeof value === "bigint") {
    return value.toString();
  }

  // 转换 Set 为常规数组
  if (value instanceof Set) {
    return Array.from(value);
  }

  // 转换 Map 为普通对象
  if (value instanceof Map) {
    return Object.fromEntries(value);
  }

  return value;
}

const serializedPayload = JSON.stringify(complexPayload, typeAdapterReplacer, 2);
console.log(serializedPayload);

3. 防范与安全处理循环引用（Circular Structure）

当对象内部存在相互引用或自引用时，默认序列化会直接报错：TypeError: Converting circular structure to JSON。可以通过在 replacer 外层维护一个已访问对象的 WeakSet，在进入循环路径时返回占位字符串：

// 示例：防止循环引用导致的崩溃
function createCircularSafeReplacer() {
  const seen = new WeakSet();

  return function (key, value) {
    if (key === "") {
      if (typeof value === "object" && value !== null) {
        seen.add(value);
      }
      return value;
    }

    if (typeof value === "object" && value !== null) {
      if (seen.has(value)) {
        return "[Circular Reference]"; // 检测到循环引用，返回标记
      }
      seen.add(value);
    }

    return value;
  };
}

// 构造自引用对象
const nodeA = { name: "Node A" };
const nodeB = { name: "Node B", parent: nodeA };
nodeA.child = nodeB; // 形成循环引用

const circularSafeJson = JSON.stringify(nodeA, createCircularSafeReplacer(), 2);
console.log(circularSafeJson);

四、结合 space 参数定制格式化缩进

JSON.stringify 的第三个参数 space 决定了输出字符串的缩进和换行样式：

• 数字类型（如 2 或 4）：每一级结构缩进相应数量的空格，数值最大受限于 10，超过 10 时会自动截断为 10。
• 字符串类型（如 " "）：使用制表符或指定字符填充缩进。例如传入 " " 时，每个层级均以一个 TAB 键对齐。

如果省略该参数或传入 null、0，输出将是单行紧凑模式，适合生产环境网络传输；而在调试排错、日志归档或生成可读配置时，结合 replacer 与 space: 2 可以获得兼顾干净与结构清晰的文本。

五、容易踩坑的关键注意事项

六、工程实践决策与总结

为了在实际开发中高效、稳健地使用 replacer 函数，下表列出了常见处理诉求与其标准实现对照：

图 4：replacer 函数工程实践决策树与安全防护总结

掌握 replacer 函数后，无需引入庞大的第三方数据清洗类库，即可利用 JavaScript 内建机制完成字段脱敏、异常类型转换与格式输出定制。在实际编写时，牢记根节点无条件放行、数组元素占位特性与普通函数 this 作用域，即可稳定可靠地构建满足各类接口与日志规范的数据流。