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 数值的表示方式
• 对其他值直接返回，不做修改，保持默认行为

示例：

Node.js 可靠编程

Node.js 可靠编程技能。避免事件循环阻塞、异步陷阱、ESM 兼容问题和内存泄漏。触发词：Node.js 开发、async/await、流处理、性能优化、安全编码。

下载

const replacer = (key, value) => typeof value === 'bigint' ? value.toString() : value;

实际使用与注意事项

将该 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;
};

这样就能在一个入口点解决多类序列化障碍，提升代码复用性与健壮性。