当前位置：首页 > 文章列表 > 文章 > 前端 > 识别 BigInt 序列化错误：JSON.stringify 深拷贝异常解决方法

识别 BigInt 序列化错误：JSON.stringify 深拷贝异常解决方法

2026-05-19 22:30:39 0浏览收藏

BigInt 类型因 JSON 标准不支持而无法被 JSON.stringify 序列化，会直接抛出明确的 TypeError 异常（提示“Do not know how to serialize a BigInt”），中断执行而非静默忽略，极易在深拷贝含大整数 ID 或高精度计数的场景中引发线上故障；本文直击该问题本质，详解如何通过控制台错误特征快速识别，并提供三种可靠解法——预处理过滤、定制 replacer 函数安全转换，以及优先推荐的现代 structuredClone() 原生方案，同时警示盲目兜底捕获的风险，助你彻底规避因 BigInt 序列化失败导致的数据错乱与隐性 Bug。

如何识别 BigInt 序列化错误：解决 JSON.stringify 在深拷贝时抛出的原始异常

当你用 JSON.stringify 对含 BigInt 的对象做深拷贝时，会直接抛出 TypeError: Do not know how to serialize a BigInt。这不是静默丢失，而是明确中断执行的原始异常，必须捕获或提前规避。

为什么 BigInt 会触发报错

JSON 标准本身不支持 BigInt 类型（它只定义了 number，且等价于 IEEE 754 双精度浮点数）。JSON.stringify 在遇到无法表示的值时，不会跳过或转成 null，而是立即 throw 错误——这和 undefined、function、Symbol 的“静默忽略”行为完全不同。

例如：

const obj = { id: 123n };
JSON.stringify(obj); // ⚠️ 抛出 TypeError

快速识别该错误的方法

在控制台或 Node.js 环境中运行时，错误堆栈中明确包含 "Do not know how to serialize a BigInt" 字样
使用 try...catch 捕获时，error.name === 'TypeError' 且 error.message.includes('BigInt')
若项目已接入错误监控（如 Sentry），该异常通常被归类为高频可定位的序列化失败类型

三种实用应对策略

提前过滤：深拷贝前遍历对象，将 typeof value === 'bigint' 的字段转为字符串（value.toString()）或安全数字（需确认是否超 Number.MAX_SAFE_INTEGER）
替换 replacer 函数：传入 JSON.stringify(obj, (key, val) => typeof val === 'bigint' ? val.toString() : val)，避免中断，但注意返回的是字符串而非 BigInt
换用现代 API：Node.js 18.13+ / Chrome 115+ 支持 structuredClone()，它原生支持 BigInt、Map、Set、Date 等，且能处理循环引用（不抛错）