JSON.stringify() 默认不支持 BigInt,需通过 replacer 函数将其转为字符串;replacer 为函数时接收 key 和 value,对 typeof value === 'bigint' 返回 value.toString() 即可安全序列化。

JSON.stringify() 默认不支持 BigInt 类型,调用时会直接抛出 TypeError: Do not know how to serialize a BigInt。但通过第二个参数——replacer 函数,可以主动拦截并转换 BigInt 值,从而实现安全、可控的序列化。
理解 replacer 参数的作用机制
replacer 可以是数组(用于白名单过滤)或函数(用于值的预处理)。当为函数时,它会在每个键值对被序列化前被调用,接收两个参数:key 和 value。只要返回一个非 undefined 的值,就会用该返回值替代原值参与后续序列化。
关键点在于:BigInt 在对象中作为属性值出现时,会被传入 replacer;而顶层的独立 BigInt(如 JSON.stringify(123n, replacer))也会触发 replacer 调用,此时 key 为空字符串 ""。
编写兼容 BigInt 的 replacer 函数
一个简洁可靠的 replacer 应满足:识别 BigInt 类型,将其转为字符串(最安全且无精度损失),同时不干扰其他类型(尤其是 Date、undefined、function 等需特殊处理的类型)。
- 使用
typeof value === 'bigint'精准判断(避免误判字符串 "123" 或数字 123) - 返回
value.toString()—— 这是唯一能完整保留 BigInt 数值的表示方式 - 对其他值直接返回,不做修改,保持默认行为
示例:
实际使用与注意事项
将该 replacer 传给 JSON.stringify 即可生效:
JSON.stringify({ id: 9007199254740991n, count: 3n }, replacer)// → '{"id":"9007199254740991","count":"3"}'
注意以下细节:
- 序列化后得到的是字符串形式的数字,解析时需手动转回 BigInt(例如
BigInt(json.id)),JSON 本身不定义 BigInt 类型 - replacer 不会影响原始数据,只作用于序列化过程中的副本
- 若对象含嵌套 BigInt(如数组元素、深层属性),replacer 会递归触发,无需额外处理
- 不要在 replacer 中返回 undefined(会导致该属性被忽略),也不要返回 NaN / Infinity(JSON 不支持)
扩展:统一处理多种不可序列化类型
可在同一 replacer 中一并处理常见问题类型,例如:
const replacer = (key, value) => {if (typeof value === 'bigint') return value.toString();
if (value instanceof Date) return value.toISOString();
if (typeof value === 'function' || typeof value === 'undefined') return null;
return value;
};
这样就能在一个入口点解决多类序列化障碍,提升代码复用性与健壮性。


















