解决JS序列化JSON时报错Converting circular structure to JSON
深入分析 JavaScript 执行 JSON.stringify 时抛出 TypeError: Converting circular structure to JSON 的根本原因,提供包含 WeakSet 过滤、属性白名单、flatted 图序列化及自定义 toJSON 等多种场景下的实用解决方案与代码示例。
JSON.stringify() 序列化包含循环引用的复杂对象、DOM 节点或双向链表时,执行引擎会因无法到达递归终止条件而直接抛出 TypeError: Converting circular structure to JSON。解决该问题的核心路径取决于业务目标:若仅需输出调试日志或部分字段,可通过 WeakSet 环标记法 或 字段白名单 忽略环状属性;若必须在网络对端完整复原对象图结构,则应选用 flatted 扁平图序列化方案。
一、问题复现与报错机制解析
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);
2. 为什么引擎必须抛出 TypeError?
JSON.stringify() 的底层实现是深度优先遍历算法。当遇到嵌套对象时,遍历器会依次递归进入每个子属性。如果对象中存在环形链路,算法就无法找到递归终止边界,若不加干涉将导致 JavaScript 调用栈溢出(Stack Overflow)。现代浏览器及 Node.js 运行时内置了环检测机制,一旦发现当前遍历路径中再次出现了已进入但尚未退出的父级对象,就会立刻阻断执行并抛出 Converting circular structure to JSON 异常。
二、排查定位:找出隐藏在数据中的循环节点
在实际企业级开发中,循环引用很少像测试用例那样显而易见,更多是由框架、第三方库或浏览器原生对象隐蔽引入的。排查此类报错时,需遵循标准步骤逐步收敛范围。
常见的循环引用隐蔽来源
-
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);
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
方案四:在业务类中实现自定义 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 报错不是单纯追求“不抛错”,更需要保证业务数据的完整性和下游系统的兼容性。下表对四种主要解决策略进行了全方位对比,方便在不同技术场景下精准选型。
五、注意事项与常见陷阱
-
勿滥用全局深拷贝: 像原生的
structuredClone()虽然内部支持循环引用结构,但其产物仍然是内存对象,而不是 JSON 字符串。如果之后依然调用JSON.stringify(structuredClone(obj)),报错依然会触发。 -
注意数组中相同非循环对象的误判: 在编写自定义的
replacer检查时,使用WeakSet记录的是当前遍历链上的祖先节点,还是所有已见过的节点。如果同一个无环子对象在数据多处被共享引用(DAG 结构),全局WeakSet.has()会将其误判为循环。若需严格区分“共享引用”与“循环引用”,应维护一个表示当前遍历栈的 Set,在离开当前节点时将其从 Set 中移除。 -
慎用正则表达式清洗: 切勿试图使用正则替换把包含
[Circular]的文本拼接修复,这极易破坏 JSON 的双引号闭合与转义规范,引发下游的SyntaxError: Unexpected token。
JS对象合并:展开运算符与Object.assign的区别及用法
2026-11-17 15:01:39
JS对象没有length属性?用Object.keys获取键数量
2026-11-17 13:21:24
JS怎么使用delete运算符删除对象属性
2026-11-17 12:47:44
JS监听Ajax/Fetch请求状态自动控制加载动画显隐
2026-11-17 11:14:07
手写JS数组倒序算法:双指针法与循环交换代码实现
2026-11-17 10:04:36






![为什么JS对象直接转字符串显示[object Object]](https://img.javascript.cn/tit/articles/13236/20261106/84aa86eb15b66540a3d64b4a7a62b181d4058395daf4aec8f716e9fa4f562f53.webp)

