JS格式化JSON时遇到循环引用报错怎么解决

一、报错重现与底层原因分析

在前端和 Node.js 开发中，循环引用（Circular Reference）是指两个或多个对象通过属性相互包含，或者一个对象的某个属性直接指向了它自身。下面的代码展示了一个最基础的成环场景：

// 构造父子双向引用的对象结构
const department = {
  name: "基础架构研发部",
  code: "DEP-01"
};

const leader = {
  name: "张工",
  title: "架构师",
  dept: department // leader 引用 department
};

department.manager = leader; // department 反向引用 leader，形成回环

// 触发序列化
JSON.stringify(department);

执行上述代码时，V8 引擎（Chrome、Node.js）会立即抛出如下异常并中断程序：

Uncaught TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'Object'
    |     property 'manager' -> object with constructor 'Object'
    --- property 'dept' closes the circle
    at JSON.stringify (<anonymous>)

在 Firefox 中，该异常的表现为 TypeError: cyclic object value。引擎之所以主动抛出错误，根源在于 JSON 规范（RFC 8259）与数据结构的内在冲突：

• JSON 标准只支持严格的树状无环层次结构：JSON 格式没有指针概念，无法用文本原生表达“引用某个已存在的对象”。
• 深度优先遍历导致调用栈无限递归：JSON.stringify 在底层采用递归方式向下序列化属性。如果遍历器不对已访问的对象进行记忆，遇到环路时就会永远在环内循环执行，最终导致 JavaScript 引擎调用栈溢出（Maximum call stack size exceeded）甚至崩溃。
• 引擎的主动防御机制：现代 JavaScript 引擎在执行序列化时维护了一个活跃对象访问路径栈。一旦检测到当前下探的对象已经存在于祖先调用栈中，便主动触发哨兵机制抛出 TypeError。

二、排查与选型决策步骤

面对循环引用报错，直接照抄代码往往无法兼顾业务需求。不同场景对序列化产物的“还原保真度”要求完全不同。遵循标准排查流程可以帮助我们在两分钟内选定最稳妥的解决方案：

1. 步骤 01：定位成环属性：观察控制台抛出的异常堆栈信息。现代浏览器已经能够清晰输出 property 'xxx' closes the circle，直接点名是哪一个字段形成了闭环。
2. 步骤 02：明确业务诉求：
   • 诉求 A（日志审计/调试打印/上报监控）：仅需要查看对象内容，不需要把 JSON 还原为具有双向引用的内存对象。此时应选择剪枝或占位策略。
   • 诉求 B（WebWorker 通信/本地持久化）：反序列化时必须 100% 完整复原对象之间的相互引用关系。此时应选择图结构拍平方案。
   • 诉求 C（接口 API 传输/状态管理）：循环引用通常源于模型设计冗余，应该在数据层进行解耦重构。
3. 步骤 03：落实技术实现：根据诉求落地对应的 Replacer、工具库或重构代码。
4. 步骤 04：验证结果与防劣化：使用 JSON.parse() 验证输出的文本是否合法，确保同值不同引用的正常对象未被误删。

三、核心解决方案一：基于 WeakSet 的自定义 Replacer 函数

JSON.stringify 原生支持第二个参数 replacer。该参数可以是一个转换函数 (key, value) => any，在递归序列化每个属性时被调用。利用 ES6 的 WeakSet，我们可以在遍历过程中记录已经访问过的对象引用。

3.1 方案 A：将循环引用标记为占位字符串（推荐用于日志与调试）

当检测到对象已被访问过时，返回 "[Circular]" 占位符。这样既能打破死循环，又能保留对象结构的层级线索，便于排查问题：

/**
 * 安全的 JSON.stringify：遇到循环引用时替换为 "[Circular]"
 * @param {any} target 要序列化的目标对象
 * @param {number|string} [indent=2] 缩进空格数
 * @returns {string} 格式化后的 JSON 字符串
 */
function safeStringifyWithPlaceholder(target, indent = 2) {
  const seen = new WeakSet();

  return JSON.stringify(
    target,
    (key, value) => {
      // 基础数据类型及 null 直接放行
      if (typeof value === "object" && value !== null) {
        // 检测到对象已经存在于遍历集合中，说明遇到回环
        if (seen.has(value)) {
          return "[Circular]";
        }
        // 首次遇到该对象，登记其引用
        seen.add(value);
      }
      return value;
    },
    indent
  );
}

// 示例运行
const nodeA = { name: "节点 A" };
const nodeB = { name: "节点 B", parent: nodeA };
nodeA.child = nodeB;

console.log(safeStringifyWithPlaceholder(nodeA));
/*
输出结果：
{
  "name": "节点 A",
  "child": {
    "name": "节点 B",
    "parent": "[Circular]"
  }
}
*/

3.2 方案 B：自动修剪掉循环引用的字段（适合 API 清洗）

如果格式化后的 JSON 需要作为请求体发送给后端，包含 "[Circular]" 字符串可能会导致后端解析或入库报错。此时可以在检测到回环时直接返回 undefined，JSON.stringify 会自动将该属性剔除：

/**
 * 剪枝型 JSON.stringify：遇到循环引用直接忽略该键
 */
function safeStringifyPrune(target, indent = 2) {
  const seen = new WeakSet();

  return JSON.stringify(
    target,
    (key, value) => {
      if (typeof value === "object" && value !== null) {
        if (seen.has(value)) {
          return undefined; // 返回 undefined 会让 JSON.stringify 忽略当前 key
        }
        seen.add(value);
      }
      return value;
    },
    indent
  );
}

四、核心解决方案二：保留完整关系的无损序列化（Flatted 方案）

在状态持久化、WebWorker 跨线程通信或离线缓存等场景中，剪除引用会导致原始数据模型失真。如果接收端必须通过 JSON.parse 重新还原出相互指向的对象图，就必须使用专门的图序列化算法。

目前社区中最成熟、应用最广泛的标准工具是 flatted（下载量超数亿，由 Jest、Circular-JSON 演进而来）。

4.1 安装与使用步骤

# 在项目中安装 flatted
npm install flatted

import { stringify, parse } from 'flatted';

// 构造相互引用的结构
const user = { name: "李四" };
const role = { title: "管理员", owner: user };
user.currentRole = role;

// 1. 无损序列化：生成扁平化索引 JSON 字符串
const serialized = stringify(user);
console.log(serialized);
// 产物示例：[["1"],{"name":"李四","currentRole":"2"},{"title":"管理员","owner":"1"}]

// 2. 无损反序列化：完美复原内存图关系
const restoredUser = parse(serialized);
console.log(restoredUser.currentRole.owner === restoredUser); // 输出: true！完全相等

4.2 原理解释：Flatted 如何打破限制

flatted 的核心设计是将深层嵌套的网状对象转化为一个二维扁平数组（Flattened Array）。数组的第 0 位记录根节点索引，其余元素依次存储拍平后的独立对象。原本对象内部的直接嵌套引用，被替换为指向数组下标的数字字符串（例如 "1"、"2"）。在执行 parse 时，再依照索引表两趟遍历重新织网，从而在标准 JSON 规范下实现了图结构的安全存取。

五、架构与数据层优化：从根源避免循环引用

循环引用不仅在序列化时报错，还容易引发深拷贝死循环、调试器展开卡顿以及状态追踪困难等工程问题。在多数业务场景下，对象间的直接双向引用其实是设计冗余，可以通过数据层规范化从根本上消除。

5.1 实体关系规范化（Normalized State）

借鉴关系型数据库的理念，不要将子对象直接挂载到父对象体内，而是通过主键 ID 进行关联：

// 优化前：存在直接指针引用，容易成环且难以维护
const badStructure = {
  id: "dept-101",
  name: "设计部",
  members: [
    { id: "u-1", name: "小王", department: null /* 挂载部门将成环 */ }
  ]
};

// 优化后：状态扁平化归一（Normalized），通过 ID 关联
const normalizedState = {
  departments: {
    "dept-101": { id: "dept-101", name: "设计部", memberIds: ["u-1", "u-2"] }
  },
  users: {
    "u-1": { id: "u-1", name: "小王", departmentId: "dept-101" },
    "u-2": { id: "u-2", name: "小李", departmentId: "dept-101" }
  }
};

// 任何节点都可以被原生 JSON.stringify 随意序列化，安全无异常
const jsonStr = JSON.stringify(normalizedState, null, 2);

5.2 提取传输对象（DTO / ViewModel 转换）

当不可避免地使用带有双向关联的 ORM 实体（如 TypeORM、Sequelize、Prisma）或复杂类实例时，在向前端返回或向外输出前，编写一个轻量的转换函数，只提取当前接口所必须的属性字段：

function toUserDTO(userEntity) {
  return {
    id: userEntity.id,
    nickname: userEntity.nickname,
    departmentName: userEntity.department ? userEntity.department.name : null
    // 不透传可能引发回环的整个 departmentEntity
  };
}

六、方案对比与总结

不同方案在实现成本、运行性能和数据保真度之间有各自的权衡。开发团队可参考以下对比矩阵进行技术选型：