cal.diy 性能优化指南：最小化 RSC 边界的序列化数据，削减页面体积与加载耗时

导读

本篇技术指南聚焦 React Server Components（RSC）架构下的一个高频性能陷阱——Server/Client 组件边界上的 props 序列化。在基于 Next.js App Router 构建的 cal.diy（Cal.com 调度基础设施）中，凡是从 Server Component 传递对象给 Client Component，对象的所有可枚举属性都会被序列化并内嵌进 HTML 与后续 RSC 请求的载荷中。读完本文，你将掌握序列化的发生机制、它如何直接影响页面体积与加载时间，以及"只传递客户端真正消费的字段"这一条核心实践及其配套的数据库查询瘦身方案。

---

什么是 RSC 边界序列化，为什么"体积即成本"

在 cal.diy 的 Web 应用（apps/web）中，页面同时存在两种组件运行环境：

• Server Components：默认环境，可以在服务端直接 await 数据、访问数据库，但不产生浏览器端 JavaScript；
• Client Components：以 "use client" 指令声明的组件，运行在浏览器端，需要 props、状态与事件交互。

当一棵组件树跨过 Server/Client 边界时（即服务端组件把 props 渲染/传递给一个客户端组件），React 需要把服务端已经就绪的数据"空运"到浏览器。正如规则文档所指出的，边界会把这些对象的所有属性序列化为字符串，并嵌入到 HTML 响应以及随后的 RSC（React Server Component）请求载荷中。这些序列化数据会同时被写入：

1. 首屏 HTML 响应里的 RSC Flight（飞行数据流）内嵌 payload；
2. 后续 RSC 导航请求的 payload 中。

因此序列化内容直接决定页面重量与加载时间，size matters a lot（体积至关重要）。

这条规则在 server-serialization.md 中被标记为 HIGH 影响、目标是减少数据传输量，是整个"Server-Side Performance"（服务端性能）类别下的五条核心规则之一（见 SKILL.md 中的优先级表）。之所以重要，是因为它带来的成本是静默的：代码能正常运行、功能看不出任何差别，但每一个多余的字段都在无谓地增大页面字节数。

---

一次传递，双重成本：为什么超发字段尤其昂贵

序列化成本并非简单"多传几个字段多几百字节"这么简单，实际代价往往被放大：

• 随首屏 HTML 传输：序列化后的数据作为 <script> 内嵌在服务端返回的 HTML 中，直接增加首字节与首屏 HTML 下载量，推迟 TTFB（Time To First Byte）之后的解析与渲染；
• 在 RSC payload 中再次出现：后续的客户端导航依赖 RSC Flight 数据重建 Server Component 输出，这些字段会被再次序列化传输；
• 拖累水合（hydration）：客户端需要读取这些序列化 props 来重建组件树，payload 越大，解析与执行成本越高。

以 cal.diy 的数据库模型为例，单看 schema.prisma 中从约第 401 行开始的 User 模型，就声明了 id、uuid、username、name、email、emailVerified、bio、avatarUrl、timeZone、weekStart、bufferTime、hideBranding、theme、createdDate 等数十个字段，还挂载着 password、travelSchedules 等关系。换句话说，一次 fetchUser() 返回的"完整用户对象"字段数量可达几十个，而客户端界面上往往只用其中一两个。

更值得警惕的是安全边界：User 模型持有 password 关联（即密码哈希等凭据数据）。如果把完整对象直接作为 props 透传给客户端组件，那么这些本应只存在于服务端的敏感字段也会被序列化进浏览器可见的 HTML 源码。最小化边界序列化不仅是性能优化，也是一道防数据泄露的保险。

---

核心规则：只传递客户端实际消费的字段

原规则通过一组对比代码精确地定义了问题与解法。假设服务端拿到的是一个含 50 个字段的用户对象。

反例：整个对象被序列化，50 个字段全部过界

async function Page() {
  const user = await fetchUser()  // 50 fields
  return <Profile user={user} />
}

'use client'
function Profile({ user }: { user: User }) {
  return <div>{user.name}</div>  // uses 1 field
}

问题所在：客户端组件 Profile 只渲染 user.name 一个字段，但由于 props 传递的是整个 user 对象，RSC 边界被迫把全部 50 个字段序列化后写入 HTML 与 RSC payload。多余的 49 个字段对渲染毫无贡献，却实打实地占用了带宽、增大了页面重量。

正例：把对象拆成原始值，只序列化被消费的 1 个字段

async function Page() {
  const user = await fetchUser()
  return <Profile name={user.name} />
}

'use client'
function Profile({ name }: { name: string }) {
  return <div>{name}</div>
}

正确做法是在 Server Component 里完成字段"裁剪"：先取到完整的 user 对象，但只把客户端真正需要的 user.name 以原始 string 值的形式传过去。此时跨越边界的只有一个字符串字段，序列化体积从 50 个字段骤降到 1 个字段。

这条规则的要点可以概括为：

1. 边界处只放基本类型与必要字段——优先传递 string、number、boolean 这样的原始值，而不是"顺手把整个对象扔过去"；
2. 字段裁剪发生在服务端——fetchUser() 可以照常取完整数据用于服务端逻辑，但发往客户端的 props 必须是精挑细选后的最小集合；
3. 可序列化约束——跨边界的数据还会受到 React Flight 序列化的格式限制，函数、Date、Map/Set、类实例方法等都无法原样穿越，一旦把大对象整传还容易在序列化环节踩坑，进一步佐证了"少传、传原始值"的必要性。

---

多字段消费场景：边界裁剪是"最小化"，不是"禁止"

反例/正例展示的是只消费 1 个字段的极端情况。更常见的情形是客户端确实需要对象里的若干字段（例如用户名、头像、时区、品牌色），此时仍要遵循同一原则：逐字段解构、按需透传，而不是整传对象后再让客户端组件自己挑选。例如：

async function Page() {
  const user = await fetchUser()
  return <Profile name={user.name} avatar={user.avatarUrl} timeZone={user.timeZone} />
}

'use client'
function Profile({ name, avatar, timeZone }: {
  name: string
  avatar: string | null
  timeZone: string
}) {
  return (
    <div>
      <img src={avatar ?? ''} alt="" />
      <span>{name}</span>
      <small>{timeZone}</small>
    </div>
  )
}

这种做法同时带来两个额外收益：

• props 契约显式化：客户端组件的入参即其全部依赖，类型签名一目了然，代码可读性、可维护性更高；
• 避免意外泄漏：对象中那些本不该暴露给浏览器的字段（如内部 id、服务端凭据、日志字段）不会因为"顺带"而流出。

需要说明的是，边界瘦身应与组件拆分策略配合：如果多个组件消费同一对象的不同字段，可以在中间插入 Server Component 作为"适配层"，为每个 Client Component 各自动手裁剪各自的 props，从而在逻辑上保持服务端数据获取的复用，在边界上依然只序列化必要字段。

---

纵深实践一：从数据库查询开始瘦身（select 优先于 include）

边界裁剪解决的是"已取回对象里挑字段"，但更彻底的做法是把筛选前移到数据访问层，让对象从源头就不带那么多字段。这一思想与本仓库中 data-prefer-select-over-include.md 规则一脉相承：用 Prisma 的 select 显式声明需要的列，而不是 include 拉取整表与全部关系。

cal.diy 服务端代码里这种"按需 select"的写法随处可见，例如 forgot-password 路由只取找回密码流程真正需要的字段：

const user = await prisma.user.findUnique({
  where: { email },
  select: { name: true, email: true, locale: true },
})

这里只回传 name、email、locale 三列，避免了 password 等敏感列与其余几十个字段被无谓读取。将这一模式与 RSC 边界裁剪叠加，会形成一条完整的瘦身链路：

1. 数据库层：select 只查客户端/服务端确实需要的列，减少 DB 传输与对象构造开销；
2. 服务端逻辑层：对数据做必要的加工、权限过滤；
3. RSC 边界层：只把客户端实际渲染要用的字段以原始值透传，杜绝整对象序列化。

反过来，如果只在边界裁剪而数据库仍整行读取，节省的只是网络传输；如果只在数据库裁剪而边界仍整传，序列化浪费依旧存在。两者缺一不可，而边界裁剪是最终决定"多少数据进入浏览器 HTML"的关键一环。

---

纵深实践二：在真实页面中判断组件边界

要落实规则，第一步是准确识别哪些组件在边界另一侧。在 cal.diy 的 apps/web/app 中，凡是需要浏览器交互能力的页面都会在文件首行声明 "use client"，例如 booking 成功页 booking-successful/[uid]/page.tsx：

"use client";

import { useParams } from "next/navigation";
// ...
export default function BookingSuccessful() {
  const params = useParams();
  const uid = params?.uid as string;
  const bookingData = useDecoyBooking(uid);
  // ...
}

这类文件的数量在仓库中相当可观——对 apps/web 的一次检索即可命中数十个 "use client" 入口（详见 apps/web/app 下各页面与组件目录）。每当你看到 "use client" 与一个 Server Component 在组件树中交汇，就应该停下来审视一遍：父级传给它的 props 是否携带了它根本用不到的对象字段？

一个实用的代码评审技巧是：直接检索页面中客户端组件消费 props 的地方（例如 booking.title、user.name、booking.startTime 这类属性访问），把它们与 Server 侧传入的对象字段集合做对比，凡是"传了但客户端从未读取"的字段都应在边界剔除。此外，善用 React 的 children/slot 组合模式可以整体规避序列化：当一段昂贵的静态 UI 不需要在客户端重新渲染时，可以把它作为 children 从服务端直接注入，而不必把承载它的数据做成 props 传过边界。

---

落地检查清单

把本文的规则固化为可执行的标准，评审 RSC 代码时可逐条对照：

1. 找出所有从 Server Component 传给 "use client" 组件的 props；
2. 逐一确认每个 props 都被客户端组件或其子树实际消费，删除"传而不用"的字段；
3. 若传的是整个对象，检查它是否携带敏感字段（如密码、token、内部 ID），并在服务端裁剪后再透传；
4. 优先传递原始值（string/number/boolean），避免为单个字段序列化整个嵌套对象；
5. 配合 Prisma select 在数据库查询阶段就缩小返回列（参见 data-prefer-select-over-include.md）；
6. 思考能否用 children/slot 组合把不需要在客户端存在的数据留在服务端，从结构上消除序列化；
7. 对优化前后对比 RSC payload 与 HTML 体积，验证收益。

---

总结

RSC 边界序列化是 Server Components 架构下"看不见的字节税"：每个多余的 props 字段都会以字符串形式沉淀在 HTML 与 RSC 载荷中，直接推高页面重量、拖慢加载。cal.diy 的 User 这类动辄几十个字段加敏感关联的 Prisma 模型，让这条规则的现实意义尤其突出。最小化边界序列化的核心只有一句话——只把客户端真正消费的字段传过去——而它与数据库 select 瘦身、children 组合式传递等模式结合后，能从数据源头到浏览器渲染形成一条完整的体积控制链路。

延伸阅读本技能集内相关规则：server-cache-react.md（React.cache() 请求内去重，减少重复取数与序列化源头）、server-parallel-fetching.md（组件组合消除服务端 waterfall），以及技能总览 SKILL.md 与完整合订本 AGENTS.md。