企业官网建设流程全解析

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI

在 React Server Components（RSC）架构下，服务器组件向客户端组件传递的每个属性都会被序列化成字符串，嵌入到 HTML 响应和后续的 RSC 请求负载中。这条由 Vercel Engineering 维护、被 ZCode 仓库以 skill 形式引入的server-serialization规则（HIGH 影响级别），正是为了解决"服务端传了 50 个字段、客户端只用 1 个"这一最常见的数据膨胀问题。读完本文，你将掌握 RSC 边界序列化的底层原理、字段裁剪的具体手法，以及它与去重、缓存、并行取数等相关规则的协同用法，能够在编写或审查 React/Next.js 代码时做出可量化收益的传输优化。

规则出处与定位

该规则位于仓库的 server-serialization.md，是 vendored 的 React/Next.js 性能优化指南react-best-practices中"Server-Side Performance（服务端性能）"分类下的第 3.6 条规则，元数据如下：

这份技能库的完整索引见 SKILL.md：共 70 条规则、8 个分类，其中服务端性能分类（server-前缀）整体为 HIGH 影响级别。在 AGENTS.md 的完整合订版中，本规则位于 3.6 小节，与server-dedup-props（3.2，避免重复序列化）、server-cache-react（3.9，请求内去重）等规则并列。根据 skills-lock.json，这套规则由vercel-labs/agent-skills引入，skillPath指向skills/react-best-practices/SKILL.md，用于指导 Agent 在编写、审查、重构 React/Next.js 代码时自动应用这些性能模式。

RSC 边界到底发生了什么

理解规则的前提，是先理解 RSC 边界序列化的机制：

1. 服务器组件在服务端执行，不打包进浏览器 JS bundle，因此可以安全地执行数据库查询、文件读取等 I/O。
2. 跨边界的属性全部字符串化：当服务器组件把对象作为 props 传给客户端组件（"use client"）时，React 需要把这个对象的每一个属性逐字段序列化为字符串。
3. 序列化结果有两处落点：初次加载时嵌入在 HTML 响应中（用于水合），之后每次 RSC 请求（导航、刷新）时携带在 RSC 负载中。两处都直接计入页面体积与传输时间。

因此规则给出的结论非常直接："This serialized data directly impacts page weight and load time, so size matters a lot. Only pass fields that the client actually uses."（序列化数据直接影响页面体积与加载时间，所以体积至关重要——只传递客户端真正使用的字段。）

这同时也意味着：数据量级的差距是逐字段放大的。一个含 50 个字段的用户对象，如果客户端只用name一个字段，那么其余 49 个字段的键名、字符串值和结构标记都在为每次页面加载和每次 RSC 导航重复买单。

反模式：整对象直传

规则给出的错误示例，是绝大多数代码库中最常见的写法——服务端拿到完整对象后原样传给客户端组件：

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 }

问题在于：fetchUser()返回的对象包含 50 个字段（如邮箱、地址、订单历史、内部标识、审计日志等），而Profile组件只渲染user.name。序列化器无法知道客户端只用 1 个字段，它只会忠实地把所有 50 个字段编码进 HTML 与 RSC 负载。对于高流量页面，这 49 个无用字段会以乘数效应放大每次请求的传输量。

正模式：只传递用到的标量

规则的修正版本，是把边界上的 props 从"整个对象"收窄为"客户端实际消费的标量字段"：

async function Page() { const user = await fetchUser(); return <Profile name={user.name} />; } ("use client"); function Profile({ name }: { name: string }) { return <div>{name}</div>; }

改动只有两行：服务端在返回 JSX 前解构出user.name，客户端组件签名改为接收name: string。序列化负载从 50 个字段降到 1 个字符串。"Incorrect (serializes all 50 fields)" → "Correct (serializes only 1 field)"，这是规则文件给出的核心对比，也是审查代码时最直接的判别标准。

实战：如何判断该裁剪哪些字段

把这条规则落地到真实代码中，可以按以下步骤操作：

第一步：盘点客户端组件的真实消费面。列出每个"use client"组件的 props 类型，逐一核对渲染函数（JSX）、事件处理器与 effect 中实际读取的属性路径。只保留被读取到的路径，其余全部从服务端 props 中剔除。

第二步：在服务器组件出口处做解构，而不是传对象。将<Profile user={user} />改为<Profile name={user.name} />。注意裁剪发生在边界上，而不是fetchUser()内部——服务端内部仍然可以使用完整对象（例如用于权限判断），只是不要把它整体推过边界。

第三步：用标量或最小化结构传递。优先传string、number、boolean等原始类型；如果需要传多条记录，只挑选每条记录中用到的字段构造一个精简数组，例如items.map(({ id, title }) => ({ id, title }))。

第四步：留意隐藏的序列化内容。对象上的Date、Map、Set、undefined、循环引用等特殊值，在 RSC 边界上要么无法序列化、要么被转换为特殊占位标记。如果对象里含有这些值，整对象直传还会额外引入序列化开销甚至报错风险，裁剪反而能规避这类边界兼容性问题。

配套规则：序列化优化的完整工具箱

server-serialization并非孤立存在。同属服务端性能分类的几条规则，构成了围绕 RSC 边界的完整优化组合，理解它们能让裁剪决策更精准：

1. 避免重复序列化（server-dedup-props）

server-dedup-props.md 指出：RSC→客户端序列化的去重是按对象引用而非按值进行的。同一引用序列化一次，新引用（如.toSorted()、.filter()、.map()、[...arr]产生的新数组）会再次完整序列化。因此：

• string[]、number[]、boolean[]派生数组去重失效时影响极大（数组与全部原始值都会重复传输）；
• object[]派生数组只重复数组外壳，内部对象按引用去重，影响较小。

推荐做法是把toSorted()、filter()等变换挪到客户端，通过useMemo按需计算。这与server-serialization的"少传"形成互补：前者解决"同一个数据传多份"，后者解决"没用的数据也传了"。

2. 配合 React.cache() 与并行取数

裁剪字段的前提是服务端能高效拿到数据。server-cache-react.md 建议用React.cache()对鉴权、数据库查询等非fetch异步操作做请求内去重（Next.js 对fetch已内置请求记忆化）；server-parallel-fetching.md 则通过组件组合让树中的多个服务器组件并发取数，消除串行瀑布。两者让"服务端取数变快"，server-serialization让"服务端到客户端的传输变少"，共同压低首屏耗时。

3. 别用模块级状态当"隐式 props"

一个常见误区是：既然不想序列化，就把用户数据塞进模块级变量，让客户端组件直接读取。这是错误的。server-no-shared-module-state.md 明确警告：服务端渲染可在同一进程内并发执行，模块级可变量会造成请求间数据串扰甚至安全漏洞。正确做法仍然是显式 props 传递 + 边界裁剪——裁剪不是绕过序列化，而是减少序列化内容。

4. 静态资源提到模块级

对于字体、Logo、配置等每次请求内容都相同的静态资产，server-hoist-static-io.md 建议把 I/O 提升到模块级，模块初始化时加载一次、请求时直接复用，避免重复的文件读取与网络抓取。这条规则与本规则的分工是：静态数据"模块级复用"，请求数据"边界裁剪"。

仓库中的实证："use client"组件实践

ZCode 仓库本身是 Electron 桌面应用 + React UI 的项目结构，packages/ui中大量组件文件顶部都声明了"use client"指令。以 agent.tsx 为例，文件头部明确写着"use client";，随后用memo包裹组件、以ComponentProps<"div">这类精简的 props 类型接收属性——这正是"客户端组件保持小而专注、props 只承载渲染所需最小集"的代码形态。AgentHeader组件同样只声明name?: string、model?: string两个展示性标量 props，而非传入完整对象。

虽然 ZCode 的桌面 UI 主要通过本地渲染而非 RSC 传输数据，但这条规则对它的意义体现在两层：其一，本仓库作为vercel-react-best-practices技能的宿主，会在 Agent 编写、审查、重构 React/Next.js 代码时自动触发该规则（见 SKILL.md 的 When to Apply 说明）；其二，"use client"边界组件 props 最小化的思想，在非 RSC 的 React 应用中同样适用——父组件传给子组件的对象越精简，依赖追踪、记忆化缓存（memo/useMemo）的命中率越高，无效重渲染越少。

边界情况：什么时候可以例外

规则并非"永远只传标量"。以下例外场景允许传递派生数据或更完整的结构：

• 变换开销昂贵：如果客户端需要的是服务端经过大量计算（聚合、排序、权限过滤）后的结果，把结果在服务端算好再传，优于让客户端重复计算——此时宁可传"少而精的派生数据"。
• 客户端确实需要原始对象：当客户端要基于完整数据做离线处理、复杂交互或多种展示形态时，评估"传全量对象"与"传精简副本"的体积差后再决定。
• 服务端对象本来就小：如果对象本身只有 2～3 个字段且全部被使用，整对象直传与逐字段解构没有实质差异，优先可读性。

另外，从安全角度审视，裁剪还能降低序列化内容泄露敏感字段（邮箱、内部 ID、计费信息等）的暴露面——即使客户端"用不到"这些字段，只要它们被序列化进 HTML 与 RSC 负载，就存在被提取的可能。"只传客户端需要的"同时就是"只暴露客户端需要的"。

检查清单

把本规则固化成代码审查与生成时的自查清单：

• 每个跨边界的 props，是否都核对过客户端组件实际读取的属性路径？
• 是否存在"传了完整对象、只渲染一个字段"的反模式？
• 服务端是否有toSorted()/filter()/map()/[...arr]产生的派生数组被重复传入边界（配合server-dedup-props检查）？
• 被裁剪的字段是否原本包含敏感信息，裁剪后是否已从序列化负载中消失？
• 是否误用模块级可变状态传递请求数据（应改为 props，见server-no-shared-module-state）？
• 静态资产是否已提升到模块级（见server-hoist-static-io），避免与请求数据争夺带宽？

RSC 边界的每一字节序列化都直接换算成页面体积与加载时间。把"只传客户端真正使用的字段"作为默认习惯，配合去重、缓存与并行取数规则，即可在数据获取到 UI 呈现的整条链路上系统性地压缩传输成本——这也正是 ZCode 以 skill 形式引入 Vercel 这份最佳实践指南的初衷：让 Agent 在生成代码时就自动遵守这些规则，而不是事后靠人工排查修复。

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI