JS格式化输出报错：怎么处理循环引用和BigInt类型数据

一、现象复现与底层报错机理

调试复杂数据结构时，直接调用原生序列化方法往往会瞬间中断程序执行。要彻底解决这两个问题，首先需要了解为何原生序列化方法会针对这两种数据类型主动抛出 TypeError。

1. 循环引用引发的堆栈保护机制

当一个对象的某个属性直接或间接指向自身或其祖先层级时，就构成了对象图中的有向闭环。例如常见的 DOM 节点关联（父节点包含子节点列表，子节点又拥有 parentNode 属性），或树状/图状业务模型：

// 构造相互引用的简单闭环
const parentNode = { name: "部门A" };
const childNode = { name: "项目组1", parent: parentNode };
parentNode.child = childNode;

// 触发运行时报错
JSON.stringify(parentNode, null, 2);
// 抛出异常: TypeError: Converting circular structure to JSON
// --> starting at object with constructor 'Object'
// |     property 'child' -> object with constructor 'Object'
// --- property 'parent' closes the circle

JSON 数据格式在 RFC 8259 规范中被严格限定为一棵有向无环树（Tree），不支持任何图状网络中的循环引用语法。JavaScript 引擎中的 JSON.stringify 在执行序列化时，采用深度优先遍历（DFS）向下递归处理属性。如果允许遍历包含闭环的对象，递归将永远无法终止，直到浏览器或 Node.js 进程耗尽调用栈而崩溃（Stack Overflow）。因此，引擎内部在遍历时跟踪当前对象层级，一旦检测到有向闭环，就会主动抛出 TypeError 进行阻断。

2. BigInt 类型与 JSON 规范的精度冲突

在处理雪花算法生成的高精度分布式 ID、区块链交易哈希或大数值计数时，现代前端和 Node.js 广泛采用原生 BigInt 类型。然而，当对包含 BigInt 的对象执行序列化时，也会立即报错：

const orderInfo = {
  orderId: 18446744073709551615n, // 64位无符号大整数 BigInt
  status: "PAID"
};

JSON.stringify(orderInfo, null, 2);
// 抛出异常: TypeError: Do not know how to serialize a BigInt

这一报错源于标准的有意设计，而非引擎遗漏。根据规范，JSON 中的数字语法对应的是 IEEE 754 双精度浮点数，其能够无损表达的连续整数上限为 Number.MAX_SAFE_INTEGER（即 2⁵³ - 1，9007199254740991）。一旦超过该阈值，普通数字类型便会发生精度截断。

如果 JSON.stringify 默认将 18446744073709551615n 转换为普通数字，输出给后端或其他系统时将丢失低位精度，带来严重的数据安全隐患；而如果将其输出为带 n 结尾的字面量（如 18446744073709551615n），又会直接破坏标准 JSON 语法解析器的兼容性。因此，ECMAScript 标准委员会决定禁止对 BigInt 进行隐式序列化，强制要求开发者在序列化前显式声明转换规则。

二、核心操作步骤：构建通用的安全序列化管道

在绝大多数业务场景中，我们既不需要引入庞大的第三方依赖，也不需要篡改全局环境。JSON.stringify(value, replacer, space) 本身就提供了极其强大的 replacer 替换函数参数。我们可以利用该参数构建一个轻量、高效的过滤拦截器。

步骤 1：避免全局污染，谨慎对待 toJSON 原型修改

社区中常见一种简便解法：直接在全局 BigInt.prototype 上挂载 toJSON 方法：

// 不推荐的全局猴子补丁写法：
BigInt.prototype.toJSON = function() {
  return this.toString();
};

步骤 2：使用 WeakSet 拦截闭环引用

在序列化单次执行周期内，使用 WeakSet 记录所有已经遍历过的对象引用。由于 WeakSet 持有的是对象的弱引用，它不会阻碍垃圾回收，且查找效率为 O(1)。

步骤 3：编写完整的 safeStringify 函数

将 BigInt 的字符串化转换与 WeakSet 的环检测整合进一个闭包函数中，形成开箱即用的格式化输出工具：

/**
 * 安全的 JSON 格式化输出函数
 * 支持处理包含循环引用和 BigInt 类型的任意数据结构
 * 
 * @param {any} data 待序列化的数据对象
 * @param {number|string} indent 缩进空格数或缩进字符，默认为 2
 * @param {object} options 配置项，可选 customBigIntHandler
 * @returns {string} 格式化后的 JSON 字符串
 */
function safeStringify(data, indent = 2, options = {}) {
  // 维护单次序列化过程中的已访问对象集合
  const seen = new WeakSet();

  const replacer = (key, value) => {
    // 1. 处理 BigInt 类型：转为字符串（或根据需要追加后缀）
    if (typeof value === "bigint") {
      if (typeof options.bigIntFormatter === "function") {
        return options.bigIntFormatter(value);
      }
      return value.toString();
    }

    // 2. 处理对象类型（排除 null）
    if (typeof value === "object" && value !== null) {
      if (seen.has(value)) {
        // 发现重复引用，输出占位标记截断死循环
        return "[Circular]";
      }
      seen.add(value);
    }

    // 3. 其他基本数据类型（string, number, boolean 等）原样返回
    return value;
  };

  return JSON.stringify(data, replacer, indent);
}

步骤 4：执行结果验证

我们编写一个综合包含循环引用与 BigInt 字段的复杂对象进行验证：

// 构造测试对象
const complexData = {
  appName: "PayGateway",
  transactionId: 9223372036854775807n, // 64-bit int
  meta: {
    version: 1,
    tags: ["core", "fintech"]
  }
};

// 引入循环引用
complexData.selfReference = complexData;
complexData.meta.root = complexData;

// 执行格式化输出
const result = safeStringify(complexData, 2);
console.log(result);

运行上述代码后，程序平稳输出以下美化后的 JSON 字符串，不再抛出任何异常：

// 示例输出结果：
{
  "appName": "PayGateway",
  "transactionId": "9223372036854775807",
  "meta": {
    "version": 1,
    "tags": [
      "core",
      "fintech"
    ],
    "root": "[Circular]"
  },
  "selfReference": "[Circular]"
}

三、算法进阶：全局 WeakSet 与祖先调用栈的边界辨析

在实际工程中，使用全局 WeakSet 虽然简单高效，但在某些特定数据结构下存在一个容易被忽视的“误伤”问题：有向无环图（DAG）中的非循环共享对象。

1. 兄弟节点共享引用的“误伤”现象

考虑如下数据结构：同一个子对象同时被两个兄弟属性所引用：

const sharedConfig = { theme: "dark", lang: "zh-CN" };
const pageState = {
  headerConfig: sharedConfig,
  footerConfig: sharedConfig
};

console.log(safeStringify(pageState, 2));
// 输出结果中：
// headerConfig 正常输出了对象内容；
// footerConfig 却输出了 "[Circular]"！

在这个例子中，pageState 内部完全不存在环路，headerConfig 和 footerConfig 只是共同引用了同一块内存地址。然而，因为 seen.add(sharedConfig) 在遍历 headerConfig 时已经将其记录，当遍历进入 footerConfig 时，全局 WeakSet 就会机械地判定其为重复引用，从而打上 [Circular] 标记，导致有效数据丢失。

2. 精准环检测：祖先路径栈机制

真正的循环引用，要求某个节点的子孙节点指向了其祖先调用链中的某一环。如果两个节点仅仅是并列分支上的引用，它们不属于循环引用。要实现完全不误伤的序列化，必须追踪深度遍历过程中的祖先栈（Ancestry Stack）：

/**
 * 高级版安全序列化：基于祖先栈深度遍历，绝不误伤共享兄弟节点
 */
function accurateSafeStringify(data, indent = 2) {
  // 维护当前递归分支的祖先对象栈
  const ancestors = [];

  return JSON.stringify(data, function(key, value) {
    // 处理 BigInt
    if (typeof value === "bigint") {
      return value.toString();
    }

    // 非对象类型直接放行
    if (typeof value !== "object" || value === null) {
      return value;
    }

    // 当遍历从深层返回上层时，需要将脱离分支的祖先节点弹出栈
    // 利用 this (当前属性的父对象) 在栈中的位置定位当前深度
    while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) {
      ancestors.pop();
    }

    // 检查当前对象是否已经在祖先调用链中（成环判断）
    if (ancestors.includes(value)) {
      return "[Circular]";
    }

    // 将当前对象入栈，作为子属性的祖先
    ancestors.push(value);
    return value;
  }, indent);
}

通过在遍历过程中维护 ancestors 栈，当遍历退出 headerConfig 分支时，sharedConfig 会自动从祖先栈中弹出；进入 footerConfig 时，由于它不在当前的祖先链上，便能被完整、正确地序列化输出。

四、全场景方案选型与工程化决策

在实际生产与开发排错中，不同场景对“格式化输出”的要求各不相同。有些场景只需在终端快速人眼查阅，有些场景需要严格传输标准 JSON，还有些场景要求接收端能够完整复原对象图。

1. 本地控制台调试：利用原生检查器（最快最方便）

如果你只是在 Node.js 服务端排查 bug 或打印日志，完全不需要调用 JSON.stringify。Node.js 官方内置的 util.inspect 已经原生支持循环引用识别与 BigInt 格式化：

const util = require("util");

const debugObj = {
  id: 10001n,
  info: "task"
};
debugObj.loop = debugObj;

// 使用 util.inspect 格式化打印
console.log(util.inspect(debugObj, { depth: null, colors: true }));
// 示例输出结果：
// <ref *1> {
//   id: 10001n,
//   info: 'task',
//   loop: [Circular *1]
// }

而在浏览器端，直接使用 console.dir(obj) 或 console.log(obj)，开发者工具的交互式控制台原生即可按需展开闭环节点并高亮显示 BigInt。

2. 数据反序列化与无损还原

如果输出的字符串未来需要通过 JSON.parse 重新还原为内存对象，单纯把 BigInt 转化为普通的数字字符串会导致类型信息丢失（反序列化后变成普通的 string 类型）。此时可以通过约定前后缀标识，配合 JSON.parse 的 reviver 参数完成闭环还原：

// 序列化时保留 BigInt 特征标识
function stringifyWithBigInt(obj) {
  return JSON.stringify(obj, (k, v) => 
    typeof v === "bigint" ? `@bigint:${v.toString()}` : v
  );
}

// 反序列化时利用 reviver 还原 BigInt 类型
function parseWithBigInt(text) {
  return JSON.parse(text, (k, v) => {
    if (typeof v === "string" && v.startsWith("@bigint:")) {
      return BigInt(v.slice(8));
    }
    return v;
  });
}

3. 复杂图结构的工业级库选型

若业务要求在客户端与服务端之间完整传输具备复杂互相引用的对象图，且对端需要原汁原味还原每个对象的内存引用关系，手写替换 "[Circular]" 会导致对象解构。此时推荐采用如下成熟方案：

• flatted：目前社区中最成熟的循环结构序列化库。它采用类似扁平表索引的机制将包含环的对象图压缩为数组，在 parse 时完美还原内存环。
• fast-safe-stringify：Node.js 高性能日志库（如 Pino）底层常用的安全序列化方案，在保持极高执行效率的同时内置循环拦截。

五、总结

在 JavaScript 中对数据对象进行格式化输出时，TypeError: Converting circular structure to JSON 与 TypeError: Do not know how to serialize a BigInt 本质上都是原生规范为了防御内存死循环与静默截断精度而设立的保护屏障。

处理这两个报错的核心思路非常明确：

1. 格式化打印与落盘场景：优先使用带有 WeakSet / 祖先栈过滤器的自定义 safeStringify 包装函数，将 BigInt 安全映射为字符串，并将闭环节点替换为易读占位符；
2. 开发调试场景：在 Node.js 中首选 util.inspect，在浏览器中首选 console.dir，省去额外编码开销；
3. 双向通信与对象还原场景：约定序列化标记搭配 JSON.parse 还原函数，或引入 flatted 实现图结构的无损重建。