识别BigInt JSON序列化崩溃原因及自定义toJSON

当你在调用JSON.stringify()时突然遇到TypeError: Do not know how serialize a BigInt，别惊讶——这是BigInt在“抗议”。它明确告诉你：JSON标准不认识这个类型，你必须自行处理转换逻辑。这一问题在实际开发中非常常见，尤其是在处理数据库大整数ID、高精度金额或计数场景时（例如Prisma或Drizzle查询返回的结果），很容易触发这个报错。

为什么原生不支持？

根本原因在于JSON标准（RFC 7159）诞生时，只定义了六种基础数据类型：字符串、数字、布尔值、对象、数组和null。BigInt是JavaScript后来引入的“新成员”，用于表示任意精度的整数，其语义和底层实现与传统的Number类型完全不同。

如果JavaScript引擎强行将BigInt降级为普通数字，会导致精度直接丢失。举个例子：9007199254740993n一旦转换成Number，就会变成9007199254740992，数据出现不可逆的错误。因此，设计上选择了最安全也最“直白”的方式：遇到无法识别的类型，直接报错，把问题暴露给开发者，而不是隐藏一个可能的数据陷阱。

toJSON 方法的作用不是“修复”，而是“声明意图”

那么，toJSON方法在这里扮演什么角色？它实际上是JSON.stringify内部的一个钩子（hook）。当序列化过程遍历到一个对象属性时，如果发现该属性值本身具有toJSON方法，就会优先调用这个方法，并用它的返回值参与序列化。

对于BigInt来说，关键点在于：

• 它本身没有内置的toJSON方法（标准未定义）。
• 当你手动为BigInt.prototype添加toJSON = function() { return this.toString(); }时，你相当于向序列化引擎发出了一条明确的指令：“以后遇到任何BigInt值，别慌，也别报错，直接用它的字符串形式替换即可。”
• 这样一来，你绕过了引擎默认的“不认识就崩溃”逻辑，将控制权握在自己手中，实现了一种可控的转换。

但要注意：toJSON 不是万能解法

这种方法看似一劳永逸，实际上存在几个明显的“坑”：

• 类型冲突：在TypeScript项目中，直接修改内置原型会导致类型检查报错，因为BigInt的官方类型定义中并不包含toJSON方法，需要额外声明或调整编译配置。
• 全局污染风险：修改内置原型是全局性操作，在大型项目、微前端架构或同时使用多个第三方库的场景下，极易引发难以追踪的冲突。
• 单向转换：它只解决了序列化（对象转字符串）的问题。反序列化（JSON.parse）时，字符串并不会自动变回BigInt，你还需要在解析端做相应的处理。

更推荐的识别与应对方式

因此，更稳健的做法不是全局“打补丁”，而是在数据序列化的入口进行集中拦截和处理。以下是几种常见的实践：

• 使用replacer函数：在调用JSON.stringify时，传入第二个参数——一个replacer函数。在函数内部判断typeof value === 'bigint'，如果是，则返回value.toString()。
• 在API响应层预处理：在框架的响应层统一处理，例如在Remix的json()辅助函数或NestJS的res.json()方法调用前，对数据进行一次扫描和转换。
• 字段命名约定：对于已知的BigInt字段，可以在命名上加入约定（如为字段名添加_big后缀），这样在反序列化时，就可以利用JSON.parse的reviver函数，精准地将这些字符串还原为BigInt类型。

说到底，处理BigInt的序列化问题，核心思路是主动识别、明确转换、保持一致性。选择一种适合你项目规模和架构的方案，远比一个看似方便的全局修改要可靠得多。