SuperJSON处理前后端传值

  在开发前后端分离或全栈应用时，我们经常需要在不同环境之间传递复杂的数据结构。使用原生 JSON.stringify 会丢失如 Date、BigInt、undefined 等类型信息，导致数据无法还原。SuperJSON 是一个增强的序列化的工具，解决了这些痛点，适用于前后端通信、本地缓存、甚至在 Redis 中安全存储复杂数据。

是什么

SuperJSON 是一个对 JSON.stringify 的增强版序列化库，可以在序列化过程中保留更多 JavaScript 原生数据类型的特性。

• 类型：Date、BigInt、undefined、Map、Set、Error、RegExp 等
• 支持嵌套结构、循环引用（可选）
• 可以在前后端之间或在缓存（如 Redis）中安全传输与还原这些数据

项目地址：https://github.com/blitz-js/superjson

特性	支持
Date、BigInt、undefined	✅ 支持
Map / Set	✅ 支持
Error、RegExp、NaN、Infinity	✅ 支持
嵌套对象、深层结构	✅ 支持
安全性	✅ 不执行代码
可用于 Redis、本地缓存、网络通信	✅ 全场景适配

能干什么

正确保留数据类型

import superjson from 'superjson'

const original = {
  date: new Date(),
  big: BigInt(12345678901234567890n),
  data: new Map([['a', 1]]),
  val: undefined,
}

const str = superjson.stringify(original)
const parsed = superjson.parse(str)

console.log(parsed.date instanceof Date) // true
console.log(typeof parsed.big) // 'bigint'
console.log(parsed.data instanceof Map) // true
console.log('val' in parsed) // true

对比标准 JSON，后者将 date 变成字符串、bigint 报错、undefined 丢失，Map 被转为普通对象。

用于 Redis 等缓存系统

在将复杂结构缓存进 Redis（如 set(key, JSON.stringify(obj))）时，默认 JSON 的局限性会导致还原后的结构与原始数据不一致。

通过 SuperJSON，我们可以这样做：

import superjson from 'superjson'
import Redis from 'ioredis'

const redis = new Redis()

const user = {
  createdAt: new Date(),
  balance: BigInt(1000),
}

const serialized = superjson.stringify(user)
await redis.set('user:1', serialized)

// 取出并反序列化
const raw = await redis.get('user:1')
const restored = superjson.parse(raw!)

console.log(restored.createdAt instanceof Date) // true

这样就可以 安全、准确地在 Redis 中存储非标准 JSON 数据结构。

使用场景

Next.js 的服务端渲染

export async function getServerSideProps() {
  const data = { createdAt: new Date(), views: BigInt(999) }
  return {
    props: superjson.serialize(data), // 返回 { json, meta }
  }
}

然后在页面组件中反序列化：

const parsed = superjson.deserialize(props)

tRPC 通信默认使用

import { createTRPCClient } from '@trpc/client'
import superjson from 'superjson'

const client = createTRPCClient<AppRouter>({
  transformer: superjson,
})

无需自己处理 Date、BigInt 等数据类型，tRPC 自动会进行序列化和还原。

状态持久化

如果要将全局状态或配置缓存到 localStorage / IndexedDB 中，也可以考虑 SuperJSON 来保证数据精度。

注意事项

• superjson.stringify() 生成的是一个带有 meta 的结构（而不是标准 JSON 字符串），建议只在双方都支持的系统中使用
• 它不能序列化函数、类实例（除非显式注册），这符合大部分需求
• 如果需要与传统 JSON.stringify 兼容格式，可通过 superjson.stringify(...).json 提取值进行兼容性存储

小结

SuperJSON 是一个强大的序列化工具，它不仅解决了传统 JSON 在类型支持上的短板，还非常适合在 前后端通信、Redis 缓存、本地存储 等各种场景下使用。在构建现代 React 或全栈 TypeScript 项目时，它能够让你 专注业务逻辑，而不是为各种数据类型对不起来而头疼。