在当今的Web开发领域，性能与用户体验始终是核心议题。React Server Components (RSC) 作为React生态系统中的一项革新性技术，旨在通过将组件渲染转移到服务器端，显著提升应用的初始加载速度、减少客户端JavaScript包大小，并实现更高效的数据获取。然而，要让服务器渲染的组件能够在客户端被正确地解析、水合（hydrate）并交互，就需要一套精巧的通信协议。这篇讲座将深入解析RSC的协议格式，探讨如何将复杂的组件结构序列化为一种特殊的JSON流，并将其发送给客户端。
RSC 的核心理念与挑战
React Server Components（RSC）的核心思想是允许开发者编写在服务器上渲染的React组件。这些组件可以访问服务器端资源（如数据库、文件系统、API密钥），并且不会将它们的代码发送到客户端。客户端只接收到渲染结果（例如HTML或更高级别的指令），以及必要的客户端组件（Client Components）的代码。
RSC带来的主要优势包括：
- 零客户端JS包大小：服务器组件的代码完全不进入客户端打包。
- 更快的初始加载：客户端需要下载、解析和执行的JavaScript更少。
- 直接数据访问：服务器组件可以直接从数据库或其他后端服务获取数据，无需客户端API层。
- 自动代码分割：RSC可以与Suspense结合，实现更细粒度的流式渲染和代码分割。
然而，RSC也带来了一个关键挑战：如何有效地将服务器端渲染的组件树的状态和结构，以一种既能被客户端理解，又能支持流式传输和异步加载的方式，发送到客户端？传统的HTML字符串渲染虽然能解决初始展示问题，但无法在客户端进行互动，也无法表达组件间的复杂关系和动态更新。这就是RSC协议应运而生的原因。
特殊的 JSON 流：RSC 协议概述
RSC协议并非简单的发送一个完整的JSON对象来描述整个组件树。它采用了一种更加复杂和强大的“特殊JSON流”格式。这种流式协议设计，旨在解决以下问题：
- 大型应用性能：避免一次性发送巨大的JSON负载。
- 异步数据与流式传输：支持服务器端组件在数据未完全准备好时，也能逐步向客户端发送内容。
- 引用与循环依赖：处理组件树中可能存在的循环引用，以及对客户端组件、服务器动作（Server Actions）的引用。
- 不同数据类型：除了标准JSON支持的数据类型外，还需要序列化React元素、Promises、错误、Maps、Sets、Date等JavaScript特有类型。
这个“特殊JSON流”本质上是一个newline-delimited JSON (NDJSON) 流，其中每一行通常是一个JSON数组，表示一个特定的指令或一个可引用的数据片段。每个指令都包含一个类型标签（通常是单个大写字母），后跟该类型所需的数据。通过这种方式，客户端可以逐行解析流，逐步构建或更新UI。
协议的核心思想：
- 标识符（ID）引用：流中的每个复杂对象（如React元素、客户端组件引用、Promises等）都会被赋予一个唯一的数字ID。后续在流中引用这些对象时，只需使用它们的ID。这有助于避免数据重复，并处理循环引用。
- 类型标签（Tag）：每个JSON数组的第一个元素是一个字符串标签，指示该数组所表示的数据类型。例如，
"J"表示一个普通的JSON值，"K"表示一个React元素，"I"表示一个客户端组件引用。 - 流式处理：客户端的RSC运行时（例如
react-server-dom-webpack或react-server-dom-esm）会持续监听这个流。一旦接收到新的指令，它就会将其解析并集成到客户端的组件树中，从而实现UI的逐步渲染和更新。
协议格式的构成要素
RSC协议定义了一系列标签，用于表示不同类型的数据和结构。理解这些标签是解析协议的关键。下面是一个核心标签的列表及其解释：
| 标签 | 类型/含义 | 序列化格式示例 | 描述 # RSC协议的序列化解析
前言：RSC 的魅力与挑战
React Server Components (RSC) 是 React 生态系统中的一项革命性功能，旨在将组件的渲染逻辑从客户端转移到服务器端，从而显著提升应用的性能和用户体验。它的核心优势在于：
- 减小客户端包体积： 服务器组件的代码及其依赖项完全在服务器上运行，不会被打包发送到客户端，大大减少了客户端需要下载和解析的 JavaScript 量。
- 更快的首次内容绘制 (FCP)： 客户端可以更快地接收到渲染完成的 UI 片段，无需等待所有 JavaScript 下载和执行。
- 更高效的数据获取： 服务器组件可以直接访问数据库、文件系统或其他后端服务，无需通过客户端 API 层进行数据往返，简化了数据流。
- 自动代码分割： RSC 与 Suspense 结合，能够实现更细粒度的流式渲染和按需加载，提升用户感知的性能。
然而，RSC 也带来了独特的挑战：服务器渲染的组件如何将其结构、状态以及对客户端组件的引用，高效、正确且可流式传输地发送给客户端，以便客户端能够进行水合（hydration）并支持交互？传统的 HTML 字符串渲染无法满足这种动态和交互式的需求。这就引出了 RSC 协议——一种特殊的 JSON 流格式。
RSC 协议：一种特殊的 JSON 流
RSC 协议并非简单地将整个组件树序列化为一个巨大的 JSON 对象。相反，它采用了一种更加精巧和强大的Newline-Delimited JSON (NDJSON) 流格式。这种设计是经过深思熟虑的，旨在解决以下关键问题：
- 流式传输 (Streaming)： 允许服务器在数据尚未完全准备好时，逐步向客户端发送 UI 片段，实现更快的用户感知加载速度。
- 引用管理： 有效处理组件树中可能存在的循环引用，以及对客户端组件、服务器动作（Server Actions）、Promises 等特殊对象的引用。
- 富数据类型支持： 除了标准的 JSON 数据类型（字符串、数字、布尔值、
null、对象、数组）外，RSC 还需要序列化 React 元素、JavaScript 内置类型（如Map,Set,Date,RegExp,BigInt,undefined）以及 Promises 和 Errors。
这个“特殊 JSON 流”的本质是：它是一个由多行 JSON 数组或值组成的文本流，每一行通常代表一个独立的指令或一个可引用的数据片段。每个指令都以一个单字符的“类型标签”开始，指明该行的内容类型，后面跟着该类型所需的数据。客户端的 RSC 运行时（例如 react-server-dom-webpack 或 react-server-dom-esm）会逐行解析这个流，并根据指令逐步构建或更新客户端的组件树。
核心设计原则
- 基于 ID 的引用： 流中所有复杂或需要被多次引用的对象（如 React 元素、客户端组件引用、Promises 等）都会被分配一个唯一的数字 ID。后续在流中引用这些对象时，只需使用它们的 ID。这不仅减少了数据冗余，也巧妙地解决了循环引用问题。
- 类型标签 (Tag) 驱动： 每个 JSON 数组的第一个元素是一个字符串标签（通常是单个大写字母），明确指示了该数组所表示的数据类型和结构。这使得协议具有很高的可扩展性，并允许客户端高效地分派处理逻辑。
- 根与更新： 协议流通常以一个“根”指令开始，表示初始的 UI 结构。随后，当服务器端的数据发生变化或异步操作完成时，协议会发送“更新”指令，告知客户端如何修改现有的 UI。
协议格式的构成要素与序列化细节
RSC 协议定义了一系列标签，用于表示不同类型的数据和结构。理解这些标签是解析协议的关键。下面是一个核心标签的列表及其解释，我们将通过代码示例来深入理解它们的序列化方式。
协议流示例结构：
<ID>:<JSON_ARRAY_OR_VALUE>其中 <ID> 是一个可选的数字 ID，用于引用该行的数据。如果该行数据不需要被引用，则可以省略 ID。
1. JSON 基础数据类型 ("J")
最基本的数据类型是普通的 JSON 值，包括字符串、数字、布尔值、null、以及由这些基本类型构成的对象和数组。它们通常以 J 标签开头，并被分配一个 ID。
服务器端组件：
// app/components/MyServerComponent.js (Server Component)
export default function MyServerComponent() {
const data = {
message: "Hello from Server!",
count: 123,
isActive: true,
details: null,
items: ["item1", "item2"]
};
return <p>{data.message}</p>;
}序列化到客户端的流：
假设 MyServerComponent 的 props 中包含上述 data 对象。当 data 对象被序列化时，它会得到一个 ID，并通过 J 标签表示：
0:["J",{"message":"Hello from Server!","count":123,"isActive":true,"details":null,"items":["item1","item2"]}]0: 这是该 JSON 值的唯一 ID。"J": 表示这是一个普通的 JSON 值。{...}: 实际的 JSON 数据。
后续如果其他部分需要引用这个 data 对象，可以直接使用 0 这个 ID。
2. React 元素 ("K")
React 元素是 RSC 协议的核心。它们包含了组件的类型和 props。
服务器端组件：
// app/page.js (Server Component)
import MyClientComponent from './MyClientComponent'; // This is a Client Component reference
export default function Page() {
return (
<div>
<h1>Welcome</h1>
<MyClientComponent text="Interactive button" />
<p>This is a server-rendered paragraph.</p>
</div>
);
}序列化到客户端的流：
假设 Page 组件被渲染。
0:["K",null,{"children":[1,2,3]}]
1:["K",null,{"children":"Welcome"}]
2:["K",{"$$typeof": Symbol(react.client.reference),"$$id":"./app/MyClientComponent.js#default"}, {"text":"Interactive button"}]
3:["K",null,{"children":"This is a server-rendered paragraph."}]
4:["K","div",{"children":[1,2,3]}]
5:["K",null,{"children":"This is a server-rendered paragraph."}]
6:["K","p",{"children":5}]
7:["K","h1",{"children":1}]
8:["K","div",{"children":[7,2,6]}](注意：实际的 ID 顺序和具体结构可能会因 React 内部实现细节而有所不同，这里仅为示例。React 的序列化器会智能地为每个节点生成 ID 并引用。)
让我们分解一个 React 元素：
8:["K","div",{"children":[7,2,6]}]
8: 这个div元素的 ID。"K": 表示这是一个 React 元素。"div": 元素的类型。如果是内置 HTML 标签，直接是字符串。{"children":[7,2,6]}: 元素的 props。这里的children是一个数组，其中7,2,6是其他元素的 ID，表示这个div的子元素。
如果是自定义组件，其类型部分会是一个引用，指向一个客户端组件（Client Component）或一个特殊的服务器组件占位符。
3. 客户端组件引用 ("C", "I")
这是 RSC 协议中最重要的部分之一。服务器组件不能直接渲染客户端组件的代码，但可以引用它们。客户端组件的引用会通过一个特殊的模块 ID 和导出名称来标识。
"C": 通常用于表示客户端模块本身，通过一个字符串路径和导出名称引用。"I": 用于表示一个客户端组件实例的引用，它会包含一个C标签的引用。
客户端组件定义：
// app/components/MyClientComponent.js (Client Component)
'use client';
import React, { useState } from 'react';
export default function MyClientComponent({ text }) {
const [count, setCount] = useState(0);
return (
<button onClick={() => setCount(count + 1)}>
{text} - Clicked {count} times
</button>
);
}服务器端组件引用：
// app/page.js (Server Component)
import MyClientComponent from './components/MyClientComponent';
export default function Page() {
return <MyClientComponent text="Click Me" />;
}序列化到客户端的流：
0:["K",{"$$typeof": Symbol(react.client.reference),"$$id":"./app/components/MyClientComponent.js#default"}, {"text":"Click Me"}]0: 这个 React 元素的 ID。"K": 表示这是一个 React 元素。{"$$typeof": Symbol(react.client.reference),"$$id":"./app/components/MyClientComponent.js#default"}: 这是组件的类型。它不是一个字符串（如 "div"），而是一个特殊的对象，标记为客户端引用。"$$typeof": Symbol(react.client.reference): 一个内部标记，指示这是一个客户端组件引用。"$$id":"./app/components/MyClientComponent.js#default": 客户端模块的路径和导出名称。客户端运行时会使用这个 ID 到客户端的模块映射中查找并加载对应的客户端组件代码。
{"text":"Click Me"}: 传递给客户端组件的 props。这些 props 必须是可序列化的 JSON 值，或对其他可序列化值的引用。
4. 服务器动作引用 ("F")
RSC 不仅支持从服务器到客户端的数据流，也支持从客户端到服务器的“动作”调用，即 Server Actions。当一个服务器函数被标记为 Server Action 时，它的引用会被序列化并发送给客户端。客户端调用这个函数时，实际上是向服务器发送一个 HTTP 请求来执行这个动作。
服务器动作定义：
// app/actions.js
'use server';
export async function submitForm(formData) {
const name = formData.get('name');
console.log(`Server received name: ${name}`);
// ... save to database ...
return `Hello, ${name}! Your form was submitted.`;
}服务器组件使用：
// app/page.js (Server Component)
import { submitForm } from './actions';
import ClientForm from './ClientForm'; // A client component
export default function Page() {
return (
<ClientForm action={submitForm} />
);
}客户端组件使用：
// app/ClientForm.js (Client Component)
'use client';
import React, { useState } from 'react';
export default function ClientForm({ action }) {
const [response, setResponse] = useState('');
const handleSubmit = async (event) => {
event.preventDefault();
const formData = new FormData(event.target);
const result = await action(formData); // Call the server action
setResponse(result);
};
return (
<form onSubmit={handleSubmit}>
<input type="text" name="name" placeholder="Enter your name" />
<button type="submit">Submit</button>
{response && <p>{response}</p>}
</form>
);
}序列化到客户端的流：
当 submitForm 函数作为 prop 传递给 ClientForm 时，它会被序列化为 Server Action 引用：
0:["K",{"$$typeof": Symbol(react.client.reference),"$$id":"./app/ClientForm.js#default"}, {"action":{"$$typeof": Symbol(react.server.reference),"$$id":"./app/actions.js#submitForm"}}]{"action":{"$$typeof": Symbol(react.server.reference),"$$id":"./app/actions.js#submitForm"}}:"$$typeof": Symbol(react.server.reference): 内部标记，指示这是一个服务器动作引用。"$$id":"./app/actions.js#submitForm": 服务器模块的路径和导出名称。客户端运行时会根据这个 ID 生成一个代理函数，当被调用时，会向服务器发送一个特殊的 HTTP 请求来触发实际的服务器动作。
5. Promises ("P")
RSC 协议支持 Promise 的流式传输。这意味着服务器可以发送一个 Promise 的占位符，并在 Promise 解决（resolve）或拒绝（reject）后，再发送实际的值或错误。这与 Suspense 紧密结合，允许在数据加载时显示 fallback UI。
服务器端组件：
// app/components/AsyncData.js (Server Component)
async function fetchData() {
await new Promise(resolve => setTimeout(resolve, 2000)); // Simulate async
return { value: "Data loaded after 2 seconds" };
}
export default async function AsyncData() {
const data = await fetchData();
return <p>{data.value}</p>;
}服务器端使用 Suspense：
// app/page.js (Server Component)
import { Suspense } from 'react';
import AsyncData from './components/AsyncData';
export default function Page() {
return (
<Suspense fallback={<p>Loading data...</p>}>
<AsyncData />
</Suspense>
);
}序列化到客户端的流：
在 AsyncData 内部，fetchData() 返回的 Promise 在服务器端被 await 了。如果 AsyncData 组件本身是一个异步组件，它会返回一个 Promise。在初始渲染时，如果 Promise 尚未解决，RSC 协议会发送一个 Promise 占位符：
0:["P"] // This line might indicate a Promise with ID 0
1:["K",null,{"children":"Loading data..."}] // Fallback UI for Suspense当 Promise 解决后，服务器会发送一个更新指令，将 Promise 的 ID 映射到其最终的值：
0:["J",{"value":"Data loaded after 2 seconds"}] // Promise with ID 0 resolved to this JSON value客户端接收到 0:["P"] 时，会创建一个客户端 Promise 占位符。当接收到 0:["J", ...] 时，客户端的 Promise 会被解决，并使用新的值进行水合。
6. 错误 ("E")
当服务器端组件在渲染过程中遇到错误时，这个错误也会被序列化并发送给客户端。客户端的 Error Boundary 可以捕获并处理这些错误。
服务器端组件：
// app/components/ErrorProneComponent.js (Server Component)
export default function ErrorProneComponent({ shouldThrow }) {
if (shouldThrow) {
throw new Error("Something went wrong on the server!");
}
return <p>No error here.</p>;
}服务器端使用 ErrorBoundary：
// app/page.js (Server Component)
import { ErrorBoundary } from 'react-error-boundary';
import ErrorProneComponent from './components/ErrorProneComponent';
function Fallback({ error }) {
return <p>Error: {error.message}</p>;
}
export default function Page() {
return (
<ErrorBoundary FallbackComponent={Fallback}>
<ErrorProneComponent shouldThrow={true} />
</ErrorBoundary>
);
}序列化到客户端的流：
当 ErrorProneComponent 抛出错误时，错误对象会被序列化：
0:["E",{"message":"Something went wrong on the server!","stack":"..."}]
1:["K",null,{"children":["Error: ",0]}] // Fallback UI referencing the error with ID 00: 错误对象的 ID。"E": 表示这是一个错误对象。{"message":"...", "stack":"..."}: 错误对象的序列化表示，通常包含message和stack属性。
7. 其他 JavaScript 内置类型
RSC 协议也支持序列化一些常见的 JavaScript 内置对象，这些对象在 JSON 中没有直接对应的表示。
| 标签 | 类型/含义 | 序列化格式示例 | 描述 |
|---|---|---|---|
"U" |
undefined |
0:["U"] |
表示 undefined 值。 |
"M" |
Map |
0:["M",[[1,2],[3,4]]] |
序列化为键值对数组的数组。 |
"A" |
Set |
0:["A",[1,2,3]] |
序列化为元素数组。 |
"V" |
BigInt |
0:["V","12345678901234567890n"] |
序列化为字符串，末尾带 n。 |
"D" |
Date |
0:["D","2023-10-27T10:00:00.000Z"] |
序列化为 ISO 8601 字符串。 |
"B" |
RegExp |
0:["B","/pattern/i"] |
序列化为字符串表示的正则表达式。 |
示例：序列化一个包含多种类型的对象
// app/components/ComplexProps.js (Server Component)
export default function ComplexProps() {
const myMap = new Map([['key1', 'value1'], ['key2', 123]]);
const mySet = new Set([1, 2, 3]);
const myDate = new Date();
const myBigInt = 12345678901234567890n;
const myRegExp = /hello/gi;
const myUndefined = undefined;
const props = {
map: myMap,
set: mySet,
date: myDate,
bigInt: myBigInt,
regExp: myRegExp,
undef: myUndefined,
message: "Complex data example"
};
return <p>{props.message}</p>;
}序列化到客户端的流 (简化示例)：
0:["D","2023-10-27T10:00:00.000Z"]
1:["V","12345678901234567890n"]
2:["B","/hello/gi"]
3:["U"]
4:["M",[["key1","value1"],["key2",123]]]
5:["A",[1,2,3]]
6:["J",{"map":4,"set":5,"date":0,"bigInt":1,"regExp":2,"undef":3,"message":"Complex data example"}]
7:["K",null,{"children":"Complex data example"}]在这个例子中，各种特殊 JavaScript 类型都被序列化成了带有各自标签的独立行，并通过 ID 在最终的 props 对象 6 中被引用。
8. 根节点 ("R")
RSC 协议流的第一个指令通常是根节点指令，它指示客户端从哪个 ID 开始渲染。
0:["R",1] // Root element is the one with ID 1
1:["K","div",{"children":[2,3]}]
2:["K","h1",{"children":"Hello"}]
3:["K","p",{"children":"World"}]这里 0:["R",1] 表示整个 RSC 树的根是 ID 为 1 的元素。
序列化与反序列化过程
服务器端序列化 (Conceptual)
在服务器端，当 React 渲染一个服务器组件树时，react-server-dom-webpack (或 react-server-dom-esm) 的序列化器会被调用。这个序列化器会遍历组件树，并执行以下操作：
- 识别可序列化类型： 区分普通 JSON 值、React 元素、客户端组件引用、服务器动作、Promises、Errors 和其他内置 JS 类型。
- 分配 ID： 为每个需要被引用的复杂对象分配一个唯一的数字 ID。
- 递归序列化：
- React 元素： 将组件类型和 props 分开序列化。类型如果是内置 HTML 标签，直接写字符串；如果是客户端组件，则序列化为客户端引用对象。props 内部的复杂值也会被递归序列化并替换为 ID 引用。
- 客户端组件引用： 生成一个包含模块路径和导出名称的特殊对象。
- 服务器动作： 生成一个包含模块路径和导出名称的特殊对象。
- Promises： 如果 Promise 尚未解决，发送一个
P标签的占位符。当 Promise 解决后，再发送一个更新指令，将 Promise ID 映射到其结果。 - Errors： 序列化错误对象的
message和stack属性。 - 其他 JS 类型： 根据其类型，使用对应的标签和特定格式进行序列化。
- 生成 NDJSON 流： 将所有序列化的数据片段（带 ID 和标签）按顺序写入一个 NDJSON 流。
伪代码示例：
// 假设这是一个简化的服务器端序列化器
function serializeRSC(element, stream) {
const visited = new Map(); // Map to store ID for already serialized objects
let nextId = 0;
function serializeValue(value) {
if (visited.has(value)) {
return visited.get(value); // Return ID if already serialized
}
const id = nextId++;
visited.set(value, id);
let serializedData;
if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) {
serializedData = ["J", value];
} else if (typeof value === 'object' && value !== null) {
if (typeof value.$$typeof === 'symbol') {
// Handle React elements, client/server references
if (value.$$typeof === Symbol.for('react.element')) {
const type = value.type;
const props = value.props;
const serializedProps = {};
for (const key in props) {
serializedProps[key] = serializeValue(props[key]); // Recursively serialize props
}
if (typeof type === 'function' && type.$$typeof === Symbol.for('react.client.reference')) {
// Client Component type, special handling
serializedData = ["K", type, serializedProps]; // type will be a client reference object
} else if (typeof type === 'string') {
// HTML tag
serializedData = ["K", type, serializedProps];
} else {
// Other React element types (e.g., Fragment, Suspense)
// Simplified: Treat as general React element
serializedData = ["K", type, serializedProps];
}
} else if (value.$$typeof === Symbol.for('react.client.reference')) {
// Client component reference object itself
serializedData = ["C", value.$$id]; // Or directly embed in K tag
} else if (value.$$typeof === Symbol.for('react.server.reference')) {
// Server action reference object itself
serializedData = ["F", value.$$id]; // Or directly embed in K tag
}
} else if (value instanceof Promise) {
serializedData = ["P"];
// Schedule resolution to write to stream later
value.then(resolvedValue => {
stream.write(`${id}:["J",${JSON.stringify(resolvedValue)}]n`);
}).catch(error => {
stream.write(`${id}:["E",${JSON.stringify({message: error.message, stack: error.stack})}]n`);
});
} else if (value instanceof Error) {
serializedData = ["E", { message: value.message, stack: value.stack }];
} else if (value instanceof Map) {
serializedData = ["M", Array.from(value.entries()).map(([k, v]) => [serializeValue(k), serializeValue(v)])];
} else if (value instanceof Set) {
serializedData = ["A", Array.from(value.values()).map(v => serializeValue(v))];
} else if (value instanceof Date) {
serializedData = ["D", value.toISOString()];
} else if (value instanceof RegExp) {
serializedData = ["B", value.toString()];
} else if (value === undefined) {
serializedData = ["U"];
} else if (typeof value === 'bigint') {
serializedData = ["V", value.toString() + 'n'];
} else if (Array.isArray(value)) {
serializedData = ["J", value.map(item => serializeValue(item))];
} else {
// Generic object
const obj = {};
for (const key in value) {
obj[key] = serializeValue(value[key]);
}
serializedData = ["J", obj];
}
} else if (typeof value === 'function' && value.$$typeof === Symbol.for('react.server.reference')) {
// Server action function itself
serializedData = ["F", value.$$id];
} else if (typeof value === 'function' && value.$$typeof === Symbol.for('react.client.reference')) {
// Client component function itself
serializedData = ["C", value.$$id];
} else {
// Unserializable type, throw error or handle gracefully
throw new Error(`Cannot serialize value: ${value}`);
}
stream.write(`${id}:${JSON.stringify(serializedData)}n`);
return id;
}
const rootId = serializeValue(element);
stream.write(`0:["R",${rootId}]n`); // Indicate the root element
}客户端反序列化与水合 (Conceptual)
在客户端，react-server-dom-webpack (或 react-server-dom-esm) 负责接收并解析这个 NDJSON 流。
- NDJSON 流解析： 客户端持续监听网络流，每接收到一行就将其解析为 JSON 数组或值。
- ID 映射构建： 客户端维护一个 ID 到实际 JavaScript 对象的映射表。当接收到
ID: [...]形式的行时，会将解析出的数据存储到这个映射表中。 - 类型标签处理： 根据每个 JSON 数组的第一个元素（类型标签），执行不同的反序列化逻辑：
"J"： 直接解析为 JavaScript 对象。"K"： 创建一个 React 元素。其type和props中的 ID 会被解析器替换为实际的 JavaScript 对象（通过 ID 映射表查找）。"C"/"I"： 解析出客户端模块的 ID (./path/to/component.js#default)。客户端运行时会根据这个 ID 查找预先构建的客户端模块清单（client module manifest），异步加载并导入对应的客户端组件代码。"F"： 解析出服务器动作的 ID。客户端会生成一个代理函数，当调用该代理函数时，会触发一个特殊的 HTTP 请求到服务器，执行实际的服务器动作。"P"： 创建一个客户端 Promise 占位符。当后续收到同 ID 的值（例如ID:["J", value]）时，解决这个 Promise。"E"： 解析为 JavaScriptError对象。- 其他 JS 类型： 根据标签和格式，构造对应的 JavaScript 内置对象（
Map,Set,Date,BigInt,RegExp等）。
- 逐步构建 UI： 当解析出完整的 React 元素（包括其子元素和 props），并且其引用的客户端组件代码也已加载完毕时，客户端 React 就会将其集成到当前的 UI 树中，进行渲染或水合。对于使用 Suspense 的异步内容，客户端会先显示 fallback，直到 Promise 解决，再水合实际内容。
伪代码示例：
// 假设这是一个简化的客户端反序列化器
function parseRSCStream(stream) {
const objectMap = new Map(); // Map to store ID to actual JS object
const promiseResolvers = new Map(); // Map to store promise resolvers
function resolveValue(id) {
if (objectMap.has(id)) {
return objectMap.get(id);
}
// If not found, it might be a Promise that hasn't resolved yet
// Or a forward reference, which will be resolved later.
// For now, return a placeholder or throw if not expected.
return id; // Return ID as a placeholder for now
}
stream.on('line', (line) => {
const parts = line.split(':');
const id = parseInt(parts[0], 10);
const data = JSON.parse(parts.slice(1).join(':'));
const tag = data[0];
const value = data[1];
let actualValue;
switch (tag) {
case "J": // JSON value
// Recursively resolve any IDs within the object/array
actualValue = deserializeRecursive(value, resolveValue);
break;
case "K": // React Element
const type = resolveValue(value); // Type can be string or client ref
const props = deserializeRecursive(data[2], resolveValue); // Props might contain IDs
actualValue = {
$$typeof: Symbol.for('react.element'),
type: type,
props: props,
key: null // Keys are not typically streamed as they are for client-side reconciliation
};
break;
case "C": // Client Component Reference
// This is where client-side module map lookup happens
actualValue = getClientComponent(value); // Function to load client component by id
break;
case "F": // Server Action Reference
actualValue = createServerActionProxy(value); // Function to create a proxy for server action
break;
case "P": // Promise
// Create a new promise and store its resolve/reject functions
let resolver;
actualValue = new Promise((resolve, reject) => {
resolver = { resolve, reject };
});
promiseResolvers.set(id, resolver);
break;
case "E": // Error
actualValue = new Error(value.message);
actualValue.stack = value.stack;
break;
case "U": // undefined
actualValue = undefined;
break;
case "M": // Map
actualValue = new Map(deserializeRecursive(value, resolveValue));
break;
case "A": // Set
actualValue = new Set(deserializeRecursive(value, resolveValue));
break;
case "V": // BigInt
actualValue = BigInt(value.slice(0, -1));
break;
case "D": // Date
actualValue = new Date(value);
break;
case "B": // RegExp
const parts = value.match(/^/(.*)/([gimsuy]*)$/);
actualValue = new RegExp(parts[1], parts[2]);
break;
case "R": // Root element
// This is the final root element to render
const rootElement = resolveValue(value);
// Trigger React's render/hydrate logic with rootElement
console.log("Root element ready for hydration:", rootElement);
return; // Don't store root in objectMap directly, it's a directive
default:
console.warn(`Unknown RSC protocol tag: ${tag}`);
return;
}
// Store the actual value in the map
objectMap.set(id, actualValue);
// If this ID was previously a Promise, resolve it
if (promiseResolvers.has(id)) {
promiseResolvers.get(id).resolve(actualValue);
promiseResolvers.delete(id);
}
});
// Helper to recursively resolve IDs in objects/arrays
function deserializeRecursive(data, resolver) {
if (typeof data === 'number') { // It's an ID
return resolver(data);
}
if (Array.isArray(data)) {
return data.map(item => deserializeRecursive(item, resolver));
}
if (typeof data === 'object' && data !== null) {
const obj = {};
for (const key in data) {
obj[key] = deserializeRecursive(data[key], resolver);
}
return obj;
}
return data;
}
}客户端模块映射 (Client Module Manifest)
当客户端接收到像 {"$$id":"./app/components/MyClientComponent.js#default"} 这样的客户端组件引用时，它需要知道如何加载这个组件的代码。这通过一个客户端模块映射 (Client Module Manifest) 来实现。
这个映射是在构建时由打包工具（如 Webpack、Vite）生成的，它将服务器端引用的模块 ID 映射到客户端可加载的 chunk 文件和导出名称。
简化的客户端模块清单示例 (Webpack 风格)：
{
"./app/components/MyClientComponent.js#default": {
"id": "abc123def", // Webpack module ID
"chunks": ["client-component-chunk.js"], // JS chunk file to load
"name": "default" // Export name within the module
},
// ... more client components
}当客户端运行时解析到 {"$$id":"./app/components/MyClientComponent.js#default"} 时，它会：
- 查阅客户端模块清单，找到对应的
id,chunks,name。 - 使用动态
import()或其他模块加载机制，加载client-component-chunk.js。 - 从加载的模块中获取
default导出，这就是实际的客户端组件代码。 - 将这个客户端组件代码与序列化过来的 props 结合，进行水合。
优势与考量
RSC 协议的优势：
- 高效流式传输： 逐行解析，支持渐进式渲染，改善用户体验。
- 精细化控制： 能够精确序列化和反序列化各种 JavaScript 类型和 React 特有结构。
- 减少重复数据： 通过 ID 引用避免了重复发送相同数据。
- 支持异步和 Suspense： 内置对 Promise 的支持，与 React 的并发模式无缝集成。
- 客户端代码零打包： 服务器组件的代码及其依赖项不会进入客户端，大幅优化客户端包体积。
开发时的考量：
- 调试复杂性： 直接阅读 NDJSON 流可能会比较困难，需要借助开发者工具或特定的调试器来理解。
- 序列化限制： 并非所有 JavaScript 对象都能被 RSC 协议序列化（例如，复杂的闭包函数、Symbol 等）。开发者需要了解这些限制，并确保传递给客户端组件的 props 是可序列化的。
- 客户端-服务器边界： 明确哪些是客户端组件，哪些是服务器组件，以及数据如何在它们之间流动，需要一定的学习曲线。
- 网络性能： 尽管是流式传输，但大量的小指令仍然会产生一定的网络开销。
结论
RSC 协议是连接服务器端 React 渲染能力与客户端交互体验的关键桥梁。它通过一种精巧的 NDJSON 流格式，结合基于 ID 的引用和类型标签，实现了对复杂组件结构、客户端/服务器引用、异步数据以及各种 JavaScript 数据类型的序列化和反序列化。理解这个协议的工作原理，对于深入掌握 RSC 的内部机制、优化应用性能以及解决相关问题至关重要。虽然其内部实现细节复杂，但其核心设计原则——流式、引用和类型驱动——为构建高性能、模块化的现代 Web 应用提供了强大的基础。