深入理解 TypeError: Converting Circular Structure to JSON 及其解决方案

2026-02-08 09:50:19 0条评论 1次阅读 0人点赞

在 JavaScript 开发过程中，你是否曾经在控制台见过这样一行令人困惑的错误信息：“TypeError: Converting circular structure to JSON”？

作为一名开发者，我们经常需要将 JavaScript 对象序列化为 JSON 字符串，以便发送到服务器或存储在本地存储中。然而，当我们试图处理那些包含“循环引用”的复杂对象时，默认的序列化机制就会崩溃。在这篇文章中，我们将深入探讨这个错误背后的根本原因，分析它为什么会在普通对象和类实例中出现，并为你提供几种专业且可靠的解决方案，帮助你彻底搞定这一棘手问题。

什么是“TypeError: Converting Circular Structure to JSON”？

简单来说，当我们在 JavaScript 中尝试使用 JSON.stringify() 方法对一个包含循环引用的对象进行转换时，就会抛出这个错误。

为了更好地理解这一点，我们需要先明白什么是 JSON（JavaScript Object Notation）。JSON 是一种轻量级的数据交换格式，它基于 JavaScript 的一个子集。JSON 的结构是树状的，这意味着数据必须是层级分明的。在 JSON 的标准中，一个对象不能包含对自身的直接或间接引用，否则这就不再是一棵“树”，而是一个“图”，这在 JSON 的解析逻辑中是无法接受的。

因此，当我们告诉 JavaScript 引擎“把这个对象变成 JSON 字符串”时，引擎会沿着对象的属性向下遍历。一旦它发现某个属性最终指向了它自己（也就是形成了一个死循环），引擎为了防止无限递归导致的堆栈溢出，就会主动抛出错误，停止序列化过程。

错误演示

让我们先看一个最直观的错误场景，以便你识别它。下图展示了控制台中典型的报错信息：

!Error Demonstration

通常情况下，你会在调用 INLINECODE84d761ee 的那一行代码看到类似 INLINECODE421145d7 的红色高亮提示。

错误产生的根本原因

为什么我们的代码里会出现这种“圈圈套圈圈”的结构？实际上，这在处理复杂的关系数据、DOM 树或类实例时非常常见。让我们详细拆解一下导致这个错误的两个主要原因。

原因 1：对象或数组中的循环引用

这是最常见的情况。假设我们有两个对象，它们互相引用，或者一个对象引用了它自己。这在很多业务逻辑中是很自然的——例如，在一个社交应用中，“用户A”关注了“用户B”，而“用户B”也关注了“用户A”；或者在一个树形结构中，子节点需要保留对父节点的引用。

问题场景：

让我们看看下面的代码示例。我们创建了一个对象 INLINECODEcaf61631，并将其自身的 INLINECODEc10a5206 属性指向了 obj 自己。

// 1. 创建一个空对象
const obj = {};

// 2. 故意创建一个循环引用：obj.circular 指向 obj 自身
obj.circular = obj;

// 3. 尝试将其转换为 JSON
// 注意：这一行会抛出错误
try {
    const jsonString = JSON.stringify(obj);
    console.log(jsonString);
} catch (e) {
    console.error("捕获到错误：", e.message);
}

代码分析：

当 INLINECODEa676d9a8 开始执行时，它会尝试序列化 INLINECODE620f1b83。它发现 INLINECODE9e60124b 有一个属性叫 INLINECODEb8bbf3b3，于是它去序列化 INLINECODE7ded54a2。结果它发现 INLINECODE6a51815c 就是 obj 本身。如果你在控制台运行这段代码，你会看到如下输出：

Hangup (SIGHUP)
/home/guest/sandbox/Solution.js:3
const jsonString = JSON.stringify(obj); // Error occurs here
                        ^

TypeError: Converting circular structure to JSON
    --> starting at object with constructor ‘Object‘
    --- property ‘circular‘ closes the circle
    at JSON.stringify ()
    ...

原因 2：类实例中的循环引用

在使用面向对象编程（OOP）时，循环引用往往隐蔽得更深。当我们实例化一个类时，我们可能会在构造函数中将某个属性赋值为 this。这通常发生在我们需要让内部方法能够访问实例本身，或者在构建链表结构、图结构等数据结构时。

问题场景：

下面的例子中，我们定义了一个 INLINECODE67ad0f6c。在构造函数中，我们将 INLINECODE15440901 指向了 this。

class errorClass {
    constructor() {
        this.data = "一些重要数据";
        // 这里创建了对自身的引用
        this.self = this;
    }
}

const obj = new errorClass();

// 尝试序列化类实例
try {
    JSON.stringify(obj);
} catch (e) {
    console.error("序列化类实例时出错：", e.message);
}

代码分析：

虽然这看起来是一个合法的 JavaScript 类定义（在运行时是完全没问题的），但当我们试图把 obj 变成字符串时，JSON 引擎会走进死胡同。控制台会提示：

TypeError: Converting circular structure to JSON
    --> starting at object with constructor ‘errorClass‘
    --- property ‘self‘ closes the circle
    ...

解决方案：如何修复这个错误

既然我们知道了问题所在，接下来就是最关键的部分——如何解决？针对不同的场景，我们有几种不同的策略。让我们一起来看看这些实用的方法。

解决方案 1：使用 replacer 函数处理循环引用

这是最通用且推荐的方法。JSON.stringify() 方法允许我们传入第二个参数，称为 replacer（替换器）。这是一个函数，它允许我们在序列化过程中拦截每一个属性值，并对其进行自定义处理。

核心思路：

我们可以利用一个 INLINECODE6a850cb7 来记录已经“见过”的对象。在序列化每一个对象属性时，我们先检查这个对象是否已经在 INLINECODE2688e32e 中了。如果是，说明我们遇到了循环引用，直接返回 INLINECODE9c5207c1 或者一个占位符字符串（如 INLINECODE5ad92e03），从而打断递归链条。

完整代码示例：

// 1. 构建一个包含循环引用的对象
const obj = {};
obj.name = "我的对象";
obj.circular = obj; // 循环引用点

// 2. 创建一个 WeakSet 用于追踪已访问的对象
// 使用 WeakSet 是为了防止内存泄漏，它不会阻止垃圾回收
const seen = new WeakSet();

// 3. 定义 replacer 函数
const jsonString = JSON.stringify(obj, (key, value) => {
    // 检查值是否为对象类型且不为 null
    if (typeof value === "object" && value !== null) {
        // 如果这个对象已经被处理过，说明遇到了循环引用
        if (seen.has(value)) {
            // 返回一个自定义的占位符，或者直接返回 undefined
            return "[Circular Reference Detected]";
        }
        // 第一次遇到该对象，将其加入 seen 集合
        seen.add(value);
    }
    // 返回原始值继续序列化
    return value;
});

console.log(jsonString);

输出结果：

{"name":"我的对象","circular":"[Circular Reference Detected]"}

为什么这样做是安全的？

使用 INLINECODE7e7858d9 是一种最佳实践。普通的数组或 Set 会保持对对象的强引用，这可能会导致你的程序在不再需要这些对象时也无法释放内存。而 INLINECODE5c00c18d 不会阻止垃圾回收器回收对象，因此非常适合用于这种临时的追踪逻辑。

解决方案 2：在类中实现自定义的 toJSON() 方法

如果你正在处理类实例，并且你希望这个类的所有实例在序列化时都遵循特定的规则，那么在类中定义 toJSON() 方法是最优雅的方式。

核心思路：

当 INLINECODEf6ff54e5 尝试序列化一个对象时，它会自动检查该对象是否有 INLINECODE2e3f587e 方法。如果有，它会优先调用这个方法，并将该方法的返回值作为最终要序列化的值。这给了我们完全的控制权，让我们可以手动剔除那些导致循环引用的属性。

完整代码示例：

class UserProfile {
    constructor(name, friend) {
        this.name = name;
        this.data = "用户敏感数据";
        // 假设这里有一个指向自身的引用，或者指向父节点的引用
        this.self = this; 
        // 也可能指向另一个对象
        this.friend = friend;
    }

    // 实现 toJSON 方法
    toJSON() {
        // 使用解构赋值分离出会导致循环的属性 (self) 和其他属性
        // 这样我们就只序列化需要保留的数据
        const { self, ...rest } = this;
        
        // 可以在这里添加额外的逻辑，比如过滤掉敏感字段
        // 返回一个新的干净对象
        return rest;
    }
}

const user1 = new UserProfile("张三");
// 哪怕代码里有 this.self = this，序列化也不会报错
const jsonString = JSON.stringify(user1);
console.log(jsonString);

输出结果：

{"name":"张三","data":"用户敏感数据"}

实战建议：

在大型项目中，如果你的数据模型经常需要序列化，建议在每个实体类中都明确实现 toJSON。这不仅能解决循环引用问题，还能让你控制哪些隐私数据不应该被发送到前端或存储到日志中。

进阶技巧与最佳实践

除了上述两种核心方法，在实际开发中，我们还可以结合其他技巧来提升代码的健壮性。

1. 使用第三方库（如 flatted 或 circular-json）

如果你不想每次都手写 INLINECODEd63bad3c 函数，或者你需要处理极其复杂的数据结构，可以使用一些成熟的第三方库。这些库专门设计用于序列化循环结构，通常会将循环引用替换为特殊的路径字符串（如 INLINECODE5f49838a）。

注意：虽然这很方便，但出于性能优化的考虑，如果只是简单的循环引用，手写 replacer 通常性能更好，因为它减少了额外的依赖和解析开销。

2. 性能优化建议

在处理“循环引用”时，使用 INLINECODE5df0dee1 或 INLINECODEe5b668ef 进行查找是必要的，但这会带来轻微的性能开销（O(1) 的查找复杂度）。如果你的对象层级非常深（例如几千层），序列化本身就会变慢。在这种情况下，你应该检查是否真的需要序列化整个对象图。

优化策略：

  • 按需提取数据：不要直接序列化整个大对象。相反，创建一个新的“视图对象”，只包含你需要发送的数据字段。
  • 深拷贝与清理：在序列化前，先使用深拷贝工具（并配合循环引用处理）复制一份数据，清理掉不需要的引用，然后再序列化。

3. 常见陷阱：不要忽略嵌套的循环

有时候循环引用并不是直接指向自己，而是 A 引用 B，B 引用 C，C 又引用 A。这被称为“间接循环引用”。上面提到的 WeakSet 方法同样适用于这种情况，因为它追踪的是对象本身的内存地址，而不在乎它在哪个层级被引用。

// 间接循环引用示例
const nodeA = { name: "A" };
const nodeB = { name: "B" };
const nodeC = { name: "C" };

nodeA.next = nodeB;
nodeB.next = nodeC;
nodeC.next = nodeA; // 这里形成了闭环

// 我们的 WeakSet 方案依然可以完美解决
const seen = new WeakSet();
const safeString = JSON.stringify(nodeA, (key, value) => {
    if (typeof value === "object" && value !== null) {
        if (seen.has(value)) return "[Circular]";
        seen.add(value);
    }
    return value;
});

console.log(safeString); 
// 输出: {"name":"A","next":{"name":"B","next":{"name":"C","next":"[Circular]"}}}

总结

在 JavaScript 开发中遇到 TypeError: Converting circular structure to JSON 并不可怕，它只是 JSON 格式限制与 JavaScript 灵活的引用机制之间的一种冲突。

在这篇文章中，我们探索了：

  • 错误的本质：JSON 是树状结构，无法原生处理图状结构的循环引用。
  • 触发场景：无论是简单的对象字面量还是复杂的类实例，只要有属性指向父级或自身，就会报错。
  • 核心解决方案：使用 INLINECODE54c6ff33 的 INLINECODE647bacbd 参数配合 INLINECODE66d0e794 来检测并替换循环引用；或者在类中实现 INLINECODEe3e5791b 方法来自定义序列化行为。

通过掌握这些技巧，你可以更加从容地处理复杂的数据交互，构建更健壮的应用程序。下次当你看到这个错误时，你就知道该从哪里入手了！希望这篇文章能帮助你更好地理解 JavaScript 的序列化机制。祝编码愉快！

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。如需转载，请注明文章出处豆丁博客和来源网址。https://shluqu.cn/35446.html
点赞
0.00 平均评分 (0% 分数) - 0 票

相关文章美国1G带宽/1T流量高速vps $17.99/年