解决JS序列化JSON时报错Converting circular structure to JSON

作者:闭包旅人时间:2026-11-17 14:48:47浏览:661

深入分析 JavaScript 执行 JSON.stringify 时抛出 TypeError: Converting circular structure to JSON 的根本原因,提供包含 WeakSet 过滤、属性白名单、flatted 图序列化及自定义 toJSON 等多种场景下的实用解决方案与代码示例。

JavaScript 疑难解决 JSON 序列化 异常排查
当在 JavaScript 中调用 JSON.stringify() 序列化包含循环引用的复杂对象、DOM 节点或双向链表时,执行引擎会因无法到达递归终止条件而直接抛出 TypeError: Converting circular structure to JSON。解决该问题的核心路径取决于业务目标:若仅需输出调试日志或部分字段,可通过 WeakSet 环标记法 或 字段白名单 忽略环状属性;若必须在网络对端完整复原对象图结构,则应选用 flatted 扁平图序列化方案。
解决JS序列化JSON时报错Converting circular structure to JSON
图 1:对象循环引用导致 JSON.stringify 异常中断与核心解决思路

一、问题复现与报错机制解析

JSON(JavaScript Object Notation)是一种纯粹的层次化数据交换格式,其标准(RFC 8259)严格要求数据必须构成一棵无环的树状结构。然而在 JavaScript 运行时的内存堆中,对象是通过指针引用互相连接的。当两个或多个对象互相指向对方,或者一个对象自身的属性指向了自身时,就构成了“循环结构”(Circular Structure)。

1. 典型的最小复现代码

以下代码模拟了开发中最简化的自引用和双向互相引用场景:

// 场景 1:直接自引用
const node = { name: "Node A" };
node.self = node; // 属性指向自身

// 场景 2:两个对象相互持有对方引用
const user = { id: 101, name: "Alice" };
const department = { title: "Engineering", leader: user };
user.dept = department; // 形成了 user -> dept -> leader -> user 闭环

// 触发序列化
JSON.stringify(user);
执行输出结果(Node.js / Chrome V8 运行环境示例):
TypeError: Converting circular structure to JSON --> starting at object with constructor 'Object' | property 'dept' -> object with constructor 'Object' --- property 'leader' closes the circle at JSON.stringify (<anonymous>) at Object.<anonymous> (/app/index.js:12:6)

2. 为什么引擎必须抛出 TypeError?

JSON.stringify() 的底层实现是深度优先遍历算法。当遇到嵌套对象时,遍历器会依次递归进入每个子属性。如果对象中存在环形链路,算法就无法找到递归终止边界,若不加干涉将导致 JavaScript 调用栈溢出(Stack Overflow)。现代浏览器及 Node.js 运行时内置了环检测机制,一旦发现当前遍历路径中再次出现了已进入但尚未退出的父级对象,就会立刻阻断执行并抛出 Converting circular structure to JSON 异常。

解决JS序列化JSON时报错Converting circular structure to JSON
图 2:标准无环树结构与循环引用结构在深度优先序列化遍历中的行为差异

二、排查定位:找出隐藏在数据中的循环节点

在实际企业级开发中,循环引用很少像测试用例那样显而易见,更多是由框架、第三方库或浏览器原生对象隐蔽引入的。排查此类报错时,需遵循标准步骤逐步收敛范围。

解决JS序列化JSON时报错Converting circular structure to JSON
图 3:排查定位循环引用的标准四步操作法

常见的循环引用隐蔽来源

  • DOM 节点或 Window 对象: 如果不小心把 event.target、DOM 元素或挂载了 DOM 的组件实例放进待序列化对象中,DOM 节点内部具有大量的 parentElement、ownerDocument、children 双向指针,必然导致循环报错。
  • 网络请求上下文(如 Axios Error): 打印或上报 Axios 捕获的异常对象时,error.config、error.request 与 error.response 内部往往持有相互引用和底层 socket 对象。直接 JSON.stringify(error) 会频繁遭遇此错误。
  • 前端框架响应式代理(Vue 3 / React Fiber): Vue 的 reactive 包装对象或 React 的组件 Fiber 节点内部维护着复杂的父子依赖拓扑图,直接对其根节点做 JSON 序列化极易触发环路。
  • 组织架构与关系型树形业务数据: 例如员工(Employee)对象中包含所属部门(Department),部门对象中又包含成员列表(employees),在双向绑定建模时必然产生环。

三、实战解决方案与完整代码

针对不同的业务场景,有四种主流的解决策略。读者可根据“是否需要保留数据”以及“是否需要逆向还原”来选取最适宜的方法。

方案一:基于 WeakSet 实现通用的安全序列化器(推荐日常日志与上报)

JSON.stringify(value, replacer, space) 的第二个参数支持传入一个 replacer 函数。我们可以借助 ES6 的 WeakSet 记录所有已经遍历过的对象引用。当检测到某个对象已经被访问过时,用占位符 "[Circular]" 替换或返回 undefined 将其跳过。

/**
 * 安全的 JSON 序列化函数
 * @param {any} data 待序列化的数据
 * @param {number} space 格式化缩进空格数
 * @returns {string} 序列化后的 JSON 字符串
 */
function safeStringify(data, space = 2) {
  const seen = new WeakSet();

  return JSON.stringify(
    data,
    (key, value) => {
      // 处理基本数据类型与 null
      if (typeof value === "object" && value !== null) {
        // 如果 WeakSet 中已存在该引用,说明检测到回环
        if (seen.has(value)) {
          return "[Circular]"; // 替换为占位文本,亦可返回 undefined 直接剔除该属性
        }
        // 首次遇到该对象,加入 WeakSet
        seen.add(value);
      }
      return value;
    },
    space
  );
}

// 验证用例
const department = { name: "研发中心" };
const employee = { name: "李工", dept: department };
department.leader = employee; // 建立双向循环引用

const jsonResult = safeStringify(employee);
console.log(jsonResult);
执行结果输出示例:
{ "name": "李工", "dept": { "name": "研发中心", "leader": "[Circular]" } }
方案优势: 使用 WeakSet 保存对象引用为弱引用,遍历结束后可由垃圾回收机制自动清理,不会引发内存泄漏;无需引入外部三方库,几行代码即可全局通用。

方案二:属性白名单过滤法(前后端接口参数清洗)

如果向后端 API 发送请求时遇到循环引用报错,通常是因为传递的对象中混入了框架生成的附加属性或 DOM 事件。此时最干净的做法是显式声明需要提交的字段。

// 方式 A:利用 JSON.stringify 的数组白名单参数
const complexUser = {
  id: 1001,
  username: "zhangsan",
  email: "zhangsan@example.com",
  domElement: document.body, // 引起循环引用的非必要字段
  self: null
};
complexUser.self = complexUser;

// 仅序列化 id、username、email 三个字段
const cleanJson = JSON.stringify(complexUser, ["id", "username", "email"]);
console.log(cleanJson);
// 输出示例: {"id":1001,"username":"zhangsan","email":"zhangsan@example.com"}

// 方式 B:使用对象解构挑出纯粹数据
function extractPostPayload({ id, username, email }) {
  return { id, username, email };
}
const payloadJson = JSON.stringify(extractPostPayload(complexUser));

方案三:使用 Flatted 库实现全量双向图序列化(用于需完整反序列化还原的场景)

若业务要求在序列化后,必须能够通过网络或存储完整重建带有循环引用关系的 JavaScript 原生对象,safeStringify 替换为 "[Circular]" 的方式会导致数据不可逆丢失。此时应当使用业界成熟的图序列化库 flatted。

# 依赖安装命令
npm install flatted
// 代码实现
const { stringify, parse } = require("flatted");

const parentNode = { title: "父级目录" };
const childNode = { title: "子级文档", parent: parentNode };
parentNode.child = childNode; // 相互引用

// 1. 序列化为支持扁平索引映射的字符串
const serialized = stringify(parentNode);
console.log("序列化文本:", serialized);

// 2. 反序列化还原
const restored = parse(serialized);
console.log("循环引用恢复验证:", restored.child.parent === restored); // 输出: true
解决JS序列化JSON时报错Converting circular structure to JSON
图 4:WeakSet 标记法与 Flatted 扁平索引法的内部实现机制对比

方案四:在业务类中实现自定义 toJSON 方法

在面向对象编程模式中,如果某个自定义类内部必然包含父指针(例如树节点、双向链表),可以在类中实现原生的 toJSON() 方法。JSON.stringify 在处理每个对象时,会优先调用该对象的 toJSON 方法并使用其返回值进行后续序列化。

class TreeNode {
  constructor(val) {
    this.val = val;
    this.children = [];
    this.parent = null; // 潜在的循环引用来源
  }

  addChild(childNode) {
    childNode.parent = this;
    this.children.push(childNode);
  }

  // 自定义序列化策略:主动忽略 parent 指针,避免死循环
  toJSON() {
    return {
      val: this.val,
      children: this.children
    };
  }
}

const root = new TreeNode("Root");
const leaf = new TreeNode("Leaf 1");
root.addChild(leaf);

// 原生直接调用,由于 toJSON 的存在不会报错
console.log(JSON.stringify(root, null, 2));

四、验证与方案选型决策

解决 Converting circular structure to JSON 报错不是单纯追求“不抛错”,更需要保证业务数据的完整性和下游系统的兼容性。下表对四种主要解决策略进行了全方位对比,方便在不同技术场景下精准选型。

解决JS序列化JSON时报错Converting circular structure to JSON
图 5:解决 JavaScript 循环引用序列化问题的技术选型决策矩阵

五、注意事项与常见陷阱

  1. 勿滥用全局深拷贝: 像原生的 structuredClone() 虽然内部支持循环引用结构,但其产物仍然是内存对象,而不是 JSON 字符串。如果之后依然调用 JSON.stringify(structuredClone(obj)),报错依然会触发。
  2. 注意数组中相同非循环对象的误判: 在编写自定义的 replacer 检查时,使用 WeakSet 记录的是当前遍历链上的祖先节点,还是所有已见过的节点。如果同一个无环子对象在数据多处被共享引用(DAG 结构),全局 WeakSet.has() 会将其误判为循环。若需严格区分“共享引用”与“循环引用”,应维护一个表示当前遍历栈的 Set,在离开当前节点时将其从 Set 中移除。
  3. 慎用正则表达式清洗: 切勿试图使用正则替换把包含 [Circular] 的文本拼接修复,这极易破坏 JSON 的双引号闭合与转义规范,引发下游的 SyntaxError: Unexpected token。
作者最新文章
相关文章
更多