从 X 的 SSR 架构出发:React 流式渲染与 Node.js Stream 的工程深挖
以 X 重写 x.com 的 SSR 架构为出发点,做了一个可运行的实验场。真正的收获不是复刻出的三类访问者,而是挖出来的 React、Node.js、Relay、Rolldown 之间不容易被发现的交互问题,以及数据、资源、故障在流式 SSR 里的完整生命周期。
X 的工程博客前阵子发了一篇 Rebuilding the global town square from scratch,讲 x.com 新 Web 应用的重写:一个服务器,按访问者(真人、搜索爬虫、链接预览 bot)决定怎么渲染;GraphQL 响应在页面里只放一份;shell 先发,其余部分随数据到达逐块流出。
我照着这篇文章做了一个能跑的实验场:wuchendi/x-ssr-reconstruct。Fastify + React 流式渲染 + Relay,用 Vite / Rolldown 构建,跑在 Platformatic Watt 上。
做完回头看,最有价值的不是"复刻出了三类访问者",那部分照着文章写并不难。有价值的是复刻过程中撞出来的问题:每个技术单独看都没毛病,放在一起才出事。 React 的写入方式碰上 Node 的 Transform,背压悄悄失效;Relay 的 dispose() 碰上一个没写清理函数的 Observable,请求根本没被取消;Rolldown 的自定义分块碰上 React 的 hydrate,同一个页面被 hydrate 了两次。这些问题哪份文档里都没写,只有把它们放进同一条链路里跑,才会出现。
这篇按三条线来写:
- 数据的生命周期:一次请求里,数据怎样从服务端交到浏览器;
- 资源的生命周期:请求、流、Relay 的查询,什么时候创建,什么时候取消和释放;
- 故障的生命周期:上游、渲染、worker 出错时,各自怎么降级。
第五节是全文的重点:这些交互问题各自的现象、是哪几个技术之间的交互导致的、怎么解决,以及用什么测试把它固定下来。 第六节反过来讲取舍:每个关键决策,为什么选现在这种做法,而不是另一种。
X 的代码不是公开的,实验场是根据文章重建的,数据全是 mock。文中关于 React 内部行为的描述来自 react-dom 19.3.1 的源码和我写的测试,标注了"从源码看"或"推测"的地方是推断,没有单独做实验验证。数字都注明了测量条件。
一、实验场与版本口径
同一个 URL,三类访问者:真人、搜索爬虫、链接预览 bot(第三节有完整对比)。
| 组件 | 版本 |
|---|---|
| React / react-dom | 19.3.1 |
| Relay(react-relay / relay-runtime / relay-compiler) | 21.0.1 |
| Vite / Rolldown | 8.3.7 / 1.2.18 |
| Fastify | 5.12.8 |
| Platformatic Watt | 3.78.0 |
| TypeScript / Vitest | 7.0.2 / 5.1.0 |
| Node.js | 本地 24.22.2;CI 和浏览器检查用 26.13.1 |
| 浏览器检查 | Playwright 1.65.0 自带的 Chromium |
文中提到的测试数量都对应 commit 7dfaa23:
pnpm turbo run test:137 个单元测试;scripts/browser-check.mjs:29 项真实浏览器检查;pnpm parity:新旧服务器的 SEO 对比,11 个路径全部一致;scripts/watt-stall-check.mjs:Watt 替换卡死 worker 的验证。
这些都在 CI 里自动运行。复现方法见附录 C。
二、一次请求的完整生命周期
2.1 时间线:loader 发起全部请求,但只等首屏那一个
先回答一个最容易被误解的问题:路由的 loader 在渲染之前发出请求,是不是要等所有请求都完成才开始渲染?
不是。loader 会把这个路由需要的查询全部发出去,但服务端只等其中一个:首屏查询。 首屏查询的结果决定两件必须在第一个字节之前确定的事:HTTP 状态码(用户不存在时是真正的 404),以及 <head> 的内容。其余查询(timeline、评论区)在 Suspense 区块里,数据到了一块就流出一块。
下面是真人访问 /ada 时的时间线。时长是 mock 的设定值:guest token 80ms、feature flags 70ms、profile 头 60ms、timeline 450ms。
时间 ──────────────────────────────────────────────────────────►
guest token ████ 并行,约 80ms
flags ███
首屏查询 ███ 约 60ms,和下面同时发出
timeline 查询 ██████████████████████ 约 450ms
页面 chunk █ 动态 import,和首屏并行
React shell ▌ 首字节:约 150ms
数据块 + 区块 ▌ 约 600ms
- 边缘层判断访问者类型(实验场里用请求头模拟)。
- Fastify 为这个请求生成 CSP nonce;带尾部标点的 URL 在这里直接 301。
- guest token 和 feature flags 并行请求。两者之间没有依赖,原文专门提到过:以前要等 guest token 回来才去请求 flags,白白多了一个串行往返。
- 匹配路由,静态路径优先于动态参数。
- loader 发出这个路由的全部查询。预览 bot 是例外:它只发首屏查询,见第三节。
- 并行等两样东西:页面 chunk 和首屏查询。 拿到后确定状态码和
<head>。 - React 开始渲染(
renderToPipeableStream),shell 一好就开始输出,这就是首字节。 - 每个查询的响应到达后,交给注入器暂存,在下一个 flush 点写进页面,排在渲染它的区块前面。
- 输出依次经过压缩和 socket。爬虫文档在压缩之前还要统计一次字节数。
- 浏览器端:先执行回放注册表脚本,再加载 CSS,CSS 加载完成后才加载 async 入口;入口执行后
hydrateRoot,shell 先 hydrate,后面每个区块在它的 HTML 和数据都到齐之后再 hydrate。 DOMContentLoaded:流式响应全部到达并解析完。注册表标记"流已结束",还在等待的查询改为请求 API;没人取走的响应保留 30 秒后清掉。- 服务端
onAllReady:所有区块都渲染完,释放这次请求的全部查询。
只等首屏查询,正是 shell 能提前发出的原因。 如果等所有查询都完成再渲染,首字节就会变成 450ms 以上,流式输出也就失去了意义。爬虫恰恰是这样:它等的是 onAllReady,/ada 的爬虫文档要约 640ms 才开始返回。
2.2 完整数据流
构建期
relay-compiler
├─► __generated__/*.graphql.ts artifact 里只有 id,没有查询文本
└─► persisted-queries.json id → 查询文本,交给 API 服务
Vite 8 / Rolldown
├─► dist/client startup-deps / startup-app / startup-names + 各页面的懒加载 chunk
└─► dist/server entry-server.js
请求期:服务端
浏览器 GET /ada
└─► 边缘层(判断访问者类型;实验场里用请求头模拟)
└─► Watt:N 个 worker 线程,健康检查替换卡死的 worker
└─► Fastify(@x-ssr/server):安全头、CSP nonce、/assets、指标
└─► 渲染路由
├─► guest token + feature flags(并行)──HTTP──► API 服务
├─► 路由 loader:loadQuery(...)
│ └─► Relay 服务端 network ──HTTP {id}──► API 服务
│ │ ├─ 校验 persisted id
│ │ └─ mock-api(GraphQL)
│ └─► 响应的 JSON 文本 ─► 注入器.pushResponse()
└─► React Fizz:renderToPipeableStream
│ write():固定大小的缓冲块,可能停在标签中间
│ flush():每轮写完调用一次,唯一安全的插入点
▼
注入器(Transform)
React 的字节直接透传,背压由 Transform 原生处理
扣留每轮最后 14 字节,以便把数据插在 </body></html> 之前
在 flush 点插入 <script type="application/json"> + __rr.p()
▼
字节预算(只对爬虫):统计字节数,超出预算报警
▼
压缩(br / gzip):每块都 flush 压缩器,不憋住流式输出
▼ pipeline:任何一层出错,整条链路一起销毁
socket ──► 浏览器
浏览器端
<head> __rr 回放注册表 → CSS(加载完成后)→ async 入口 + modulepreload
<body> shell → [数据块 + __rr.p()] → 区块 → [数据块 + __rr.p()] → 区块 …
hydrateRoot:shell 先 hydrate,每个区块在它的 HTML 和数据都到了之后再 hydrate
Relay 客户端 network
├─ 流里已经有这个响应:直接重放(JSON.parse)
├─ 服务端还在请求:等它出现在流里
└─ 流已结束仍然没有:POST /i/api/graphql {id}(由边缘层转发到 API 服务)
降级上报:sendBeacon ──► /i/api/client-events
取消链路
客户端断开
└─► 响应的 'close' 事件(并且 !writableFinished)
└─► stream.abort():React 停止渲染
└─► 对这次请求的所有 PreloadedQuery 调用 dispose()
└─► Relay 取消订阅网络层的 Observable
└─► AbortController.abort():上游 fetch 中止
这条链路上,React、Node.js、Relay、Rolldown 各管一段。第五节的问题,几乎都出在两段交接的地方。
2.3 每个请求创建、并在结束时释放的资源
| 资源 | 创建 | 释放 |
|---|---|---|
| CSP nonce | 请求开始时(onRequest 钩子),存在以请求对象为键的 WeakMap 里 | 随请求对象一起被回收 |
AbortController(断开检测) | 渲染路由开始时;监听响应的 'close' 事件 | 客户端提前断开时触发;正常结束时不触发 |
| Relay 环境和 Store | 每个请求一个,Store 不做缓冲 | 随请求结束被回收 |
各个查询的 PreloadedQuery | loader 发出查询时 | onAllReady、中止、超时、onShellError 时统一 dispose() |
| 渲染超时定时器 | 开始渲染时(默认 10 秒) | 渲染完成、中止或出错时清除 |
| 注入器、字节统计、压缩器 | 每个请求一条流水线 | React 结束输出(正常或中止)后,整条 pipeline 结束 |
三、三类访问者的完整对比
| 真人 | 搜索爬虫 | 链接预览 bot | |
|---|---|---|---|
| 开始输出的时机 | onShellReady,shell 好了就输出 | onAllReady,全部渲染完再输出 | onAllReady |
| 输出内容 | shell + 逐块流出的区块 | 一份完整文档,区块原地展开 | 只有 <head> |
| 发出的 GraphQL 查询 | 首屏 + 正文 | 首屏 + 正文 | 只有首屏 |
| 数据块注入页面 | 是 | 否 | 否 |
| JS / hydration | 加载并 hydrate | 不加载 | 不加载 |
progressiveChunkSize | 默认(12800) | 无穷大,禁止外置(见 5.1 ③) | 无穷大 |
<head> | title、description、canonical、语言链接、OG | 同左,另外加 JSON-LD | 同真人 |
| 不存在的账号 | 真正的 404 + noindex | 真正的 404 + noindex | 真正的 404 + noindex |
| 字节预算 | 无 | 2MB,超出时记录 | 无 |
Cache-Control | private, no-store | private, no-store | private, no-store |
| 压缩 | 按 Accept-Encoding 协商 | 同左 | 同左 |
/ada 实测 | 首字节约 200ms,帖子约 650ms | 约 640ms 后一次性返回 22KB | 约 190ms,1.3KB |
有两点需要说明。
为什么三类访问者都是真正的 404。 状态码由首屏查询决定,而首屏查询在第一个字节之前就已经完成了,所以流式输出也能返回正确的状态码。如果首屏数据也放在 Suspense 里,等发现用户不存在时,200 早就发出去了。
预览 bot 是怎么做到不请求正文的。 每个路由的 loader 把查询分成两组:首屏(primary)和正文(body)。正文组只用在 Suspense 区块里,<head> 只依赖首屏组。预览 bot 走的是 loadRoute(env, route, params, { headOnly: true }),在渲染开始之前就跳过了正文组,所以评论区那个 650ms 的查询根本不会发出去。只跳过渲染正文是不够的:查询在 loader 阶段就已经发出了,上游照样会白白干活。
四、Relay 响应回放:时序与匹配规则
4.1 时序
服务端 HTTP 流 浏览器
loader 发出查询
<head>
<script> 回放注册表 __rr
CSS → async 入口 + modulepreload
React 输出 shell ───────────► shell HTML ─────────────────────► 解析并显示 shell
入口加载后 hydrateRoot:shell 先 hydrate
loadQuery(timeline) → 注册表里还没有
→ 登记等待者
timeline 响应到达
注入器暂存 JSON 文本
下一个 flush 点 ────────────► <script type=application/json ─► __rr.p():把文本放进注册表,
data-rr="KEY">…</script> 移除这两个 script 节点,
<script>__rr.p()</script> 唤醒 KEY 的等待者
React 输出区块 ─────────────► 区块 HTML + $RC ───────────────► $RC 把区块放到正确位置
等待者 JSON.parse → Relay 写入 Store
区块 hydrate
onAllReady:释放所有查询
</body></html> ────────────────► DOMContentLoaded:流已结束
仍在等待的查询 → POST /i/api/graphql {id}
30 秒后清掉没人取的响应
4.2 匹配规则
请求键是"操作名 + 变量",不是操作 id。
// 服务端和浏览器用同一个函数
export function requestKey(params: RequestParameters, variables: Variables): string {
return `${params.name}:${stableStringify(variables)}`
}- 操作 id(persisted query 的 SHA256)标识的是查询文本。同一个查询带不同的变量(比如
screenName: "ada"和"grace")是不同的响应,所以键里必须包含变量。 - 变量要做稳定序列化:对象的键按字母排序,任意层级都是。服务端和浏览器各自构造变量对象,键的顺序不一定一样,序列化结果必须一致。这一点有单元测试。
4.3 几种边界情况
| 情况 | 处理 |
|---|---|
| 响应先到,组件还没 hydrate | 以 JSON 文本的形式存在注册表里,等组件来取时才 JSON.parse |
| 组件先请求,响应还在路上 | 登记等待者;响应到达时 __rr.p() 唤醒它 |
| 多个响应到达顺序不同 | 注册表按键存取,和到达顺序无关 |
| 同一个键被请求两次 | 第一次取走后就从注册表里删掉;第二次找不到,如果流已结束就去请求 API |
| 服务端那边失败了,流里没有这个响应 | 等待者一直等到 DOMContentLoaded,然后改为请求 API |
取消订阅(dispose()) | 移除等待者;如果已经在请求 API,就中止这个 fetch |
| 流结束后没人取走的响应 | 保留 30 秒(给紧接着打开的弹窗或标签页用),然后清掉 |
| 响应里有错误,并且根字段全部为 null | 视为失败;服务端不会注入这种响应,浏览器端自己请求时同样按失败处理(见 5.4) |
五、技术之间的交互问题
5.1 React × Node.js:写入、flush 与背压
① 只能在 flush() 时插入数据,而且这个钩子只有 Node 版有
往 React 的输出里插 <script>,第一反应是在每次 write() 之后插,但这是错的。从源码看,Node 版的 Fizz 把输出写进固定大小的缓冲块,写满一块就调用一次 destination.write(),所以一次 write() 完全可能停在 <div cla 这种位置。真正的边界在每一轮写入结束的地方:
// react-dom-server.node.production.js(19.3.1)
function flushBuffered(destination) {
'function' === typeof destination.flush && destination.flush()
}
// 每轮写完:completeWriting(destination); flushBuffered(destination)React 每写完一轮(shell、每个完成的 Suspense 区块、最后的 </body></html>)都会调用 destination.flush(),所以注入器实现一个 flush() 方法,只在这个时候插入数据。
这个钩子只有 Node 版有。Web Streams 版(renderToReadableStream,Bun 和 edge 运行时用的就是它)的构建产物里没有 flushBuffered,completeWriting 只是往流里放数据。在那里做同样的注入,只能退回"缓冲一下,等这一轮任务结束再插入"这种依赖时序的推断。运行时的选择,会直接决定这套数据注入方案的正确性有没有保证。
② 整页就是 shell 时,</body></html> 已经在第一轮里了
页面没有任何待定区块时(比如一个 404 页面),第一轮 flush 就已经带上了 </body></html>。把数据追加在后面,脚本就跑到了 </html> 之后。插入时需要判断:这一轮如果正好以 </body></html> 结尾,数据要插在它前面。
③ onAllReady 不等于"内容原地展开"
爬虫要的是不依赖 JS 的完整 HTML,自然会想到用 onAllReady。但拿到的爬虫文档里还是有 <template>、<div hidden id="S:0"> 和一段 $RC 脚本,内容要靠 JS 搬回原位。
原因是 react-dom 19.3.1 的"外置"逻辑:已经输出的字节数加上某个区块的大小,超过 progressiveChunkSize(默认 12800 字节)时,即使这个区块已经完成,也会被挪到文档末尾,再用脚本搬回去。20 条帖子的 timeline 正好超过这个值。
renderToPipeableStream(element, {
progressiveChunkSize: audience === 'person' ? undefined : Number.POSITIVE_INFINITY,
})④ Transform 的背压例外:慢客户端让服务端缓存了整页
这是我觉得最隐蔽的一个。注入器第一版的设计很直观:在 _transform 里把 React 的字节攒起来,等 flush() 被调用时,把这些字节和数据一起输出。
测试:渲染 300 个 Suspense 区块,每个 5000 字节,下游一个字节都不读。React 照样把 1,542,668 字节(约 1.54MB)全部写进了注入器,完全没有暂停。这里的 1.54MB 指的是下游没读的时候 React 写进来的字节数:它们全部堆在流的缓冲区里,也就是服务端内存里;不是进程的总内存。
原因在 Node 的 Transform 实现里:
// Transform.prototype._write(节选)
const length = rState.length
this._transform(chunk, encoding, (err, val) => {
if (val != null) this.push(val)
if (length === rState.length || rState.length < rState.highWaterMark) {
callback() // 立即确认写入
} else {
this[kCallback] = callback // 推迟确认:背压生效
}
})length === rState.length 的意思是"本次转换没有产生输出",这时候一律立即确认。注入器每次写入都只攒不输出,正好每次都命中这个例外。写入方永远收到成功,React 永远不会暂停。
React 的设计(在 flush 时才是安全点)和 Node 的设计(没有输出就当作没有压力)各自都合理,放在一起,背压就悄悄消失了。
第一版修法是在 _transform 里自己判断积压,积压时扣住回调,等 _read 被调用时再放行。结果测出死锁。我的分析是:Readable 调用一次 _read 之后,在有新数据被 push 之前不会再调用 _read。注入器扣着回调在等 _read,_read 在等新数据,而新数据要等 React 继续写才会有。
最后的方案是换个思路,让 React 的字节直接透传:在 _transform 里立即 push,Transform 原生的背压机制就能正常工作。只有我们自己的数据脚本,仍然等到 flush 点才插入。为了处理 ② 的边界情况,注入器始终扣留每一轮最后 14 个字节,正好是 </body></html> 的长度。
override _transform(chunk: Buffer, _enc: BufferEncoding, cb: TransformCallback) {
const bytes = Buffer.concat([this.#tail, chunk])
const keep = Math.min(DOC_END.length, bytes.length)
if (bytes.length > keep) this.push(bytes.subarray(0, bytes.length - keep))
this.#tail = bytes.subarray(bytes.length - keep)
cb()
}数据的三条插入顺序规则都保留了:不出现在 <!DOCTYPE> 之前;先于渲染它的那个区块;整页在一轮里输出完时,插在 </body></html> 之前。同样的测试再跑一遍,下游停住时 React 提前暂停,恢复读取后 300 个区块完整到达。
另外,从源码看,React 只在区块和区块之间检查 write() 的返回值,因写满而暂停时,退出前仍会调用一次 flush()。透传方案能成立,依赖的正是这两点。
⑤ onError 先于 onShellError,shell 之前的区块错误被丢掉了
shell 本身渲染失败时,React 先调用 onError,再调用 onShellError。我最初的写法是"shell 发出之前的 onError 一律不记录",想避免重复记录。结果另一类错误也被一起丢掉了:某个区块的数据在 shell 发出之前就失败了。它只是一个可以交给浏览器去渲染的区块错误,不是 shell 错误,但日志里一条都没有。
改法是每个错误都记录,唯独 shell 本身的错误除外。因为 onShellError 在后面才被调用,判断要推迟到微任务里做:
onShellError(err) { shellError = err; reject(err) },
onError(err) {
queueMicrotask(() => { if (err !== shellError) log(err) })
},5.2 Node.js Stream × Fastify:流的所有权
① 挂一个 'data' 监听,丢了所有字节
给爬虫文档加大小预算时(Google 官方文档写的是 Googlebot 对 HTML 这类文件只抓取前 2MB,按解压后的大小计算;2022 年的旧说法是 15MB),我随手在一个 PassThrough 上挂了 'data' 监听来计数,测试也通过了。
但 'data' 监听会让流立即进入流动模式,数据一边产生一边往外流,不管有没有人接。而 Fastify 要跑完异步的 onSend 钩子之后才开始读取响应流,在那之前流出的字节全部丢失。测试能过,是因为测试里的消费者恰好是同步接上的。
补一个"消费者晚 20ms 才开始读"的测试,拿到的是空响应。改成在 Transform 里计数:
const counter = new Transform({
transform(chunk, _enc, cb) { bytes += chunk.length; cb(null, chunk) },
flush(cb) { if (bytes > budget) onExceed(bytes); cb() },
})
return pipeline(body, counter, () => {})② pipe 不传递错误
上面用的是 pipeline,不是 body.pipe(counter)。pipe 只负责搬运数据和处理背压,上游出错时不会让下游跟着销毁,下游会一直挂着等数据。这条链路串了好几层(React → 注入器 → 计数 → 压缩 → socket),任何一层出错,都应该让整条链路一起结束。
③ 压缩器会把流式输出憋住
zlib 的压缩器默认会攒够一定数据量才输出。直接接在 HTML 流后面,shell 也要等攒满了才发出去。解法是每写入一块就强制刷出一次:
_transform(chunk, _enc, cb) {
this.#z.write(chunk)
this.#z.flush(() => cb()) // 注入器只在 React 的 flush 边界输出,这里每块正好对应一轮
}我一度怀疑压缩层也有 5.1 ④ 那种背压问题,测了发现没有:压缩器是在确认写入之前就把数据 push 给下游的,Transform 的检查能看到输出,背压是正常的。同一个 Transform,输出时机不同,行为就完全不同。
④ 怎么判断客户端提前断开
Node 的 HTTP 响应对象在连接关闭时会触发 'close' 事件,但这个事件在正常写完之后也会触发,要用 writableFinished 区分:
reply.raw.on('close', () => {
if (reply.raw.writableFinished) return // 正常结束
disconnected.abort(new Error('client disconnected'))
})5.3 Relay × React × Node:取消与生命周期
① dispose() 了,请求却没取消
Relay 的 PreloadedQuery.dispose() 会做两件事:释放对数据的保留,以及取消网络请求。但"取消"靠的是对网络层 Observable 取消订阅,如果 Observable.create 里没有返回清理函数,取消订阅什么也不会发生。浏览器端和服务端两套 network 我一开始都没写,所以 fetch 照常跑完,回放注册表里的等待者也一直挂着。
Observable.create((sink) => {
const cancel = new AbortController()
fetchGraphQL(id, variables, cancel.signal).then(/* ... */)
return () => cancel.abort() // 没有这一行,dispose() 只做了一半
})而 React 的 stream.abort() 只会停止渲染,不会碰 Relay。所以服务端中止或超时的时候,还要主动对这次请求的所有 ref 调用 dispose(),取消链路才是完整的(见 2.2 的数据流图)。
② 导航竞态
客户端导航要等两样东西:路由的 chunk 和预加载的数据。连点两个链接、或者连按后退时,先发起的导航可能后完成,结果覆盖掉较新的页面,而且它的 ref 永远不会被释放。加一个"只有最新一次导航才能提交"的闸门,过期的导航完成后自己释放 ref。
③ Store 的生命周期要显式配置
Relay Store 默认会缓冲 10 个刚被释放的查询,数据也永不过期。我把它显式配置成:浏览器端缓冲 10 个(后退时直接复用,不用重新请求),数据 5 分钟后过期;服务端每个请求一个 Store,不做缓冲。测试直接驱动真实的 relay-runtime 和 loadQuery,换回默认配置时测试会失败。
④ 有条件地调用 hook,被 context 读取掩盖了
Biome 报了一处 primary ? usePreloadedQuery(...) : null。按理说这会让两次渲染的 hook 数量不一致,React 应该直接报错,但我反复导航都没触发。
原因在 React 的实现细节:读取 context 不会在 hook 链表里占位置。没有 primary 查询的那个分支里一个 hook 都没调用,于是 React 把下一次渲染当作"首次挂载"处理,"hook 变多"和"hook 变少"的检查都被绕过了。
不崩溃不代表没问题:从 Profile 后退到首页时,usePreloadedQuery 内部 effect 的清理被静默跳过了;而且以后只要有人在这个组件开头加一个 useMemo,就会立刻崩溃。最后拆成了两个组件。
5.4 Relay × GraphQL × React:流式 SSR 下的错误语义
① 错误冒泡到根,页面显示为一片空白
一个非空字段出错时,GraphQL 的规则是错误向上冒泡,把父级置为 null,一直冒到根:{ data: { post: null }, errors: [...] }。Relay 在有数据时会忽略字段错误,结果评论区显示成一片空白,用户看不出任何失败。
我定了一个策略,服务端和浏览器端都应用:
- 有错误,并且根字段全部为 null:视为整个操作失败,交给区块的错误边界,显示"加载失败,重试";
- 有错误,但部分根字段有数据:作为部分成功保留数据,并记录日志;
- 没有错误的 null:照常表示"不存在"。
服务端判定为失败的响应不注入页面。React 会把这个区块交给浏览器去渲染,浏览器发现流里没有对应的响应,就自己去请求 API。
② onRecoverableError 只在真正恢复时才会被调用
"服务端区块失败、交给浏览器"在 React 里叫可恢复错误。我想把它上报出去,于是写了一个端到端测试:让评论区在服务端和浏览器端都失败。结果可恢复错误一直是 0。
React 只有在浏览器端真正恢复成功时才会调用 onRecoverableError;浏览器端也失败的话,就只会触发区块的错误边界。测试场景本身设计错了。最后改成只给页面的文档请求加上失败开关(用 Playwright 的 page.route 拦截),浏览器自己的 API 请求不带:评论区被浏览器恢复出来,可恢复错误也被正确计数。
③ 状态码 200 不代表没有降级
这是 ① 的推论。负载测试时,评论区的上游请求超时了,页面照样返回 200,压测工具显示一切正常。要发现这类问题只有两条路:从服务端日志里统计,或者让浏览器把它看到的降级用 sendBeacon 报回来。这两条现在都做了。
5.5 Relay × TypeScript × Vite × Node ESM:开发环境
① 类型 import 在开发模式下变成了运行时 import
开发模式下,页面直接返回 500,报错是 relay-runtime 没有名为 ConcreteRequest 的导出。这是四个组件一起造成的:
- Relay 生成的 TS 文件用普通
import { ConcreteRequest } from 'relay-runtime'引入一个纯类型; - tsconfig 开了
verbatimModuleSyntax,Vite 的开发 SSR 于是原样保留这条 import; - Node 的 ESM 加载器加载 CommonJS 包时,找不到这个具名导出,直接报错;
- 生产构建由 Rolldown 打包,它对 CommonJS 的兼容处理会把这个导出当作 undefined,所以问题一直被生产构建掩盖着。
解法是在 Relay 配置里加 useImportTypeSyntax: true,让它生成 import type。
② 两个 watch 的问题
- relay-compiler 的
--watch依赖 watchman。没有 watchman 的话,改了 GraphQL 查询忘记重跑 codegen,页面就会读到旧的生成文件,控制台里只留一条很容易被忽略的提示。我写了一个只在开发服务器上生效的 Vite 插件:保存含有graphql标签的文件时自动编译,并且跳过生成目录,避免自己触发自己。另外,开了 persisted queries 之后,relay-compiler 要求映射文件在编译前就已经存在,所以 codegen 脚本会在文件不存在时先写一个{}。 node --watch和 Vite 的临时文件打架:node --watch会跟踪所有被 import 的文件,包括 Vite 把vite.config.ts编译出来、用完即删的临时 bundle。删除被当成"文件变化",服务端重启,重启时又生成临时文件,就这样无限循环。改用--watch-path只监视需要的目录。
5.6 Rolldown × Vite × React:启动分块
X 原文把启动代码合成三个 chunk:依赖、自有代码、懒加载 chunk 的文件名映射。最后这个每次发版都会变,单独拆出来,前两个的缓存才不会失效。我用 Rolldown 的 output.codeSplitting.groups 实现,连着踩了三个坑。
① includeDependenciesRecursively 默认是 true
"文件名映射"这个组把它的依赖(React、Relay)全拉了进去,从 0.87KB 变成了 285KB。
② 两个启动 chunk 互相 import
路由表既要 eager 引入每个路由的 loader(业务代码),又要声明懒加载的页面(文件名映射),结果 startup-app 和 startup-names 互相 import。运行时报 Cannot read properties of undefined (reading 'default')。负责文件名映射的模块只能包含动态 import,所以把它单独拆成了一个文件。
③ 入口模块被收进共享 chunk,同一个页面被 hydrate 了两次
这是 Rolldown 和 React 之间最有意思的一个交互。入口模块本身也被我的分组函数收进了 startup-app,入口文件只剩一行 import "./startup-app.js"。于是登录和未登录两个入口的顶层代码都会执行:boot(false) 和 boot(true) 同时对同一个 document 调用 hydrateRoot。React 报 #418(hydration 不匹配),客户端发出重复请求,/home 还被匹配到了错误的路由。
自定义分块时,入口模块要排除在共享组之外(ctx.getModuleInfo(id).isEntry)。这个问题从构建产物上几乎看不出来,现在有一个测试专门检查:每个入口文件只调用它自己的 boot()。
5.7 CSP × React × 浏览器
生产模式启用了 nonce CSP,script-src 里没有 'unsafe-inline',这里有三个交互点:
- React 自己也会输出内联脚本:流式渲染时,React 用
$RC之类的脚本把区块内容搬到正确的位置,这些脚本必须带上 nonce,要通过renderToPipeableStream({ nonce })传进去。 - 浏览器在解析之后会隐藏 nonce 属性:
getAttribute('nonce')返回空字符串,只有.nonce属性还保留着真实的值。浏览器端需要的话,要从script.nonce读取。 style-src同样会拦截内联的style属性:一个图标 sprite 上写了style={{ position: 'absolute' }},最后改成了 CSS class。
5.8 URL 解析 × 安全
开放重定向:URL 清洗规则会把 /ada. 这种带尾部标点的地址 301 到 /ada。它先对路径做 decodeURIComponent,再去掉标点,然后直接跳转,于是:
//evil.com.被跳到了//evil.com,这是协议相对地址,浏览器会直接去外站;/%2Fevil.com.解码后也是同样的结果;/\evil.com.会被浏览器当成//evil.com处理。
修了重定向之后,又发现一个相关问题://evil.com. 不再跳转了,但返回 200,渲染的是首页。原因是渲染入口用 new URL(url, base) 解析请求路径,而 //evil.com. 被当成协议相对 URL,路径就成了 /。改成按字面截取路径,这类请求就是 404 了。
5.9 浏览器 × React 流式显示
刷新后恢复滚动位置时被截断到 0
滚动位置存在 sessionStorage 里,刷新后在 DOMContentLoaded 时恢复。存储、key、页面最终高度都没问题,结果却是 0。
推测原因:DOMContentLoaded 时 HTML 虽然已经到齐,但 React 会把多个 Suspense 区块的显示攒在一起批量进行,当时 timeline 还隐藏着,页面不够高,滚动被截断了。这一点没有单独验证。修法是之后最多 2 秒内每帧重试一次,用户一开始滚动就停止。
crypto.randomUUID() 只能在安全上下文中使用
我一开始用它给每条历史记录生成 key。但它只在 https 或 localhost 下才存在,通过普通 http 的其他地址访问时,导航会直接报错。key 只需要在当前标签页内唯一,改用 Math.random() 就够了。
六、为什么不采用其他方案
前面讲的都是"怎么做"。这一节讲"为什么这么做,而不是另一种做法"。
| 问题 | 当前方案 | 另一种做法 | 选当前方案的主要原因 |
|---|---|---|---|
| 服务端数据怎么交给浏览器 | 原样回放 GraphQL 响应 | 序列化整个 Relay Store | 不依赖 Relay 的内部格式;体积更小;可以随区块逐个流出(6.1) |
| 页面怎么输出 | React 流式 SSR | 全部渲染完再一次性输出 | 首字节约 150ms,等全部渲染完要约 610ms(第八节) |
| 多种访问者 | 一个服务器,按访问者类型选策略 | 三套独立的 SSR 服务 | 路由、<head>、数据请求只有一份实现(6.3) |
| 服务端并发 | Watt 多 worker | 单个 Node 进程 | 渲染是 CPU 密集的;卡死的 worker 能被替换 |
| 启动分块 | 自定义 Rolldown 分组 | 默认自动分块 | 改业务代码不会让依赖的缓存失效(6.4) |
| 数据注入 | 输出流上的 Transform | 在 React 组件里渲染 <script> | 和组件树解耦,插入时机由 flush() 决定(6.5) |
| 运行时 | Node 版 Fizz(renderToPipeableStream) | Web Streams 版(renderToReadableStream) | 只有 Node 版有 flush() 和逐区块背压(6.2) |
下面展开其中几项。
6.1 为什么不序列化 Relay Store?
X 原文给的理由是体积:规范化之后的记录是原始响应的 4 到 5 倍。我在实验场里实际测了一下(同样的查询,一边记录原始响应,一边把查询完成后的 Store 序列化):
| 页面 | 原始响应 | Store 序列化 | 比例 | gzip 后 | 浏览器端恢复耗时 |
|---|---|---|---|---|---|
/ada | 6,270 字节 | 7,360 字节 | 1.17× | 495 vs 771 字节 | 回放 322µs,恢复 Store 52µs |
/ada/status/1001 | 5,210 字节 | 6,305 字节 | 1.21× | 528 vs 841 字节 | 回放 364µs,恢复 Store 72µs |
两个结果都和直觉不太一样。
体积只多了约 20%,不是 4 到 5 倍。 Store 里每条记录都要多带 __id、__typename,引用要写成 {"__ref":"u1"},列表写成 {"__refs":[…]}。这些结构开销是按记录数算的。mock 数据里每条帖子带着一大段正文,正文占了大头,结构开销就显得小了。真实的 X 数据,一条推文有几十个短字段和嵌套实体,结构开销的比例会高得多;原文还提到旧架构会把 Store 的每一次更新都流式发出去,同一条记录可能重复传输。所以 4 到 5 倍在 X 的场景里是可信的,只是我这里没有复现出来。值得注意的是,gzip 之后差距反而拉大到了约 1.6 倍:原始响应里的重复内容(同一个作者出现 20 次)压缩效果很好,规范化后这些重复已经被去掉了,压缩的空间变小了。
恢复 Store 反而更快。 直接用序列化的记录构造 RecordSource,比把响应重新规范化快 5 到 6 倍。这是序列化 Store 方案真正的优势:浏览器省掉了规范化这一步。不过绝对值只有几百微秒,和网络传输比可以忽略。
所以不序列化 Store,体积不是唯一的原因。更重要的是下面两点:
- 版本兼容。 Store 的序列化格式是 relay-runtime 的内部格式:
__ref、__refs、posts(first:20)这种存储键的写法,都不是公开的契约。服务端和浏览器必须运行完全相同版本的 relay-runtime,发版期间新旧版本混跑时,要么失败,要么出现很难排查的数据错误。原始 GraphQL 响应只依赖 schema 和查询文本,而 persisted query 的 id 本来就是查询文本的哈希,查询变了 id 就变,天然不会错配。 - 流式输出。 原始响应可以和每个区块一起,到一个流出一个。Store 是一个整体,要分批流出,就得计算"这一轮新增了哪些记录",等于重新实现一套 Store 的增量同步。
6.2 为什么不用 Web Streams?
5.1 ① 已经提到,只有 Node 版的 Fizz 会在每一轮写完时调用 destination.flush()。这里要强调的是:这不是部署环境的选择,而是决定了这套注入方案能不能成立。
从 react-dom 19.3.1 的构建产物看,两个版本有两处根本差别:
Node 版(renderToPipeableStream) | Web Streams 版(renderToReadableStream) | |
|---|---|---|
| 写入对象 | 你提供的 Writable,React 调用它的 write() | React 自己创建的 ReadableStream,内部直接 controller.enqueue() |
| "这一轮写完了"的信号 | 调用 destination.flush() | 没有,构建产物里没有 flushBuffered |
| 背压 | 检查 write() 的返回值,写满就停,等 'drain' | writeChunkAndReturn 永远返回 true;流开始流动后,完成的区块都会直接 enqueue |
第一处差别意味着:在 Web Streams 版上做注入,只能在 React 的流外面套一个 TransformStream。它能看到每一块字节,但不知道哪里是一轮的结束,插入点只能靠时序推断(比如"等这一轮任务结束再插入")。5.1 ① 说过,write() 的边界不可靠,插错位置就会把 <script> 插进一个标签的中间。
第二处差别是我读源码时发现的,没有单独测试:Web Streams 版在流开始流动之后,就不再根据下游的读取速度暂停了。5.1 ④ 那个"下游不读,React 也不该一直写"的保证,在 Node 版上有测试固定;在 Web Streams 版上,要靠运行时的流实现来兜底。
所以选 Node(以及 Fastify、Watt)不只是部署偏好。这套数据注入方案的正确性,依赖 Node 版 Fizz 独有的两个行为。 如果哪天要迁移到 edge 运行时,注入器需要重新设计,而不是换个 API 就行。
6.3 为什么不用三套独立的 SSR 服务?
三类访问者的需求差别很大:真人要流式输出和 hydration,爬虫要完整的文档,预览 bot 只要 <head>。直觉上,三套各自优化的服务更简单。我没有这样做,原因不只是维护成本:
- 路由行为必须一致。 同一个 URL 对三类访问者必须匹配到同一个路由、返回同一个状态码。带尾部标点的 URL 301、不存在的账号 404、静态路径优先于动态参数,这些规则只要有两份实现,迟早会不一致。
- SEO 元数据必须一致。 爬虫看到的 title、canonical、语言链接,必须和真人看到的一样;否则就是搜索引擎所说的 cloaking。当前方案里,三类访问者共用每个路由的
head()函数,差别只在爬虫额外带 JSON-LD。 - API 请求的定义只有一份。 三类访问者用的是同样的 loader、同样的 persisted query。如果是三套服务,查询文本可能各写一份,任何一份漏改,都会悄悄地多请求或少请求字段。
- 部署和资源只有一套。 一个服务、一组 worker、一套健康检查和监控。三套服务意味着三份容量规划,还要在边缘层分流,不同服务的版本还可能在发版期间短暂错开。
- 升级和回归测试的成本。 React、Relay 升级时,只需要在一个服务上跑一遍测试。现在的单元测试和浏览器检查都覆盖了三类访问者,换成三套服务,这些测试要么写三份,要么只能覆盖其中一套。
SEO 对比脚本可以说明"两份实现"的风险有多大。为了验证脚本,我在旧服务器里故意保留了四处和新服务器不同的行为(og:type、x-default 语言链接、404 页面的 noindex、尾部标点的 301)。脚本第一次运行,11 个路径全部有差异。这几处差异都是故意留的,但 X 原文说,他们在真实迁移中发现的正是这类问题。
当前方案里,三类访问者的差别集中在 entry-server.tsx 的几个分支里:是否注入数据、progressiveChunkSize、在 onShellReady 还是 onAllReady 时开始输出、预览 bot 跳过正文查询。代价是这几个分支要小心维护,每个分支都要有测试覆盖。
6.4 为什么不用默认分块?
我对比了两种分块方式,并且做了一个实验:只改一行业务代码(Timestamp.tsx 里的一个分隔符),重新构建,看哪些文件的哈希变了。
| 默认自动分块 | 自定义分组 | |
|---|---|---|
| 依赖放在哪里 | 分散在以业务模块命名的 chunk 里:boot 234KB、PostCard 266KB | 单独一个 startup-deps,482KB |
| 改一行业务代码后,哈希变了的文件 | boot 和 PostCard,共约 500KB,以及几个页面 chunk | startup-app 约 25KB,以及几个页面 chunk 和文件名映射 |
startup-deps | — | 不变 |
默认分块按模块之间的引用关系切分,依赖和业务代码混在同一个 chunk 里。改一行业务代码,用户就要重新下载约 500KB(gzip 后约 140KB)的 JS,其中绝大部分是根本没变的 React 和 Relay。自定义分组把"经常变的"和"几乎不变的"分开,代价就是 5.6 里那三个坑。
6.5 为什么不在 React 组件里注入数据?
另一种做法是:每个用到数据的组件,在自己旁边渲染一个 <script type="application/json">。这样不需要 Transform,注入时机由 React 决定。我没有实现这个方案,下面是从现有设计推断的几个问题:
- 数据和组件绑在一起。 同一个查询被多个组件用到时,要么注入多次,要么要协调由谁注入。而当前方案里,注入单位是"一个网络响应",和组件结构无关。
- hydration 时要渲染出同样的内容。 React 渲染的
<script>是组件树的一部分,浏览器 hydrate 时必须渲染出同样的节点,否则就是 hydration 不匹配。也就是说,浏览器在 hydrate 时还要拿着同一份 JSON 文本;而当前方案在__rr.p()执行后就把这两个 script 节点删掉了,它们根本不在 React 的管辖范围内。 - 响应和区块的时机不同。 响应通常比渲染它的区块更早到达(查询在 loader 里就发出了)。放在 Transform 里,响应一到就能在下一个 flush 点写出去;放在组件里,就只能等组件渲染时才输出。
- 三类访问者的差别。 爬虫和预览 bot 不需要这些数据。放在组件里,每个用到数据的组件都要知道"现在是不是真人访问";放在 Transform 里,只需要在一个地方决定要不要
pushResponse。
代价是 Transform 本身的复杂度:flush 时机、背压、流的所有权,也就是第五节前两小节的那些问题。这部分复杂度集中在一个有测试覆盖的模块里,而不是分散在每个组件中。
七、故障场景矩阵
把第五节里分散的错误处理合在一起:
| 故障 | 服务端 | 浏览器 | 怎么验证的 |
|---|---|---|---|
| guest token、flags 或首屏查询失败/超时(shell 之前) | 页面请求返回 500 HTML 错误页(no-store);API 请求返回 JSON | — | 手动:把上游超时设为 1ms |
| shell 本身渲染出错 | onShellError → 500 HTML 错误页 | — | 走同一个错误处理器 |
| 正文查询失败(HTTP 层面) | 不注入数据,区块交给浏览器,并记录日志 | 流结束后自己请求 API:成功就恢复,并上报"可恢复错误";失败就显示区块错误和重试按钮,并上报"区块错误" | 浏览器检查 H1、H1b、H2、H4 |
| 正文查询返回错误,并且根字段为 null | 按失败处理(同上) | 同上 | 单元测试,浏览器检查 H3 |
| 部分成功(部分根字段有数据) | 保留数据,记录日志 | 正常渲染,console.warn | 单元测试 |
| 渲染超过 10 秒 | stream.abort(),未完成的区块交给浏览器,释放查询 | 自己请求数据 | 单元测试 |
| 客户端提前断开 | 中止渲染,释放查询,中止上游请求,计入 renders.aborted | — | 单元测试,手动 curl |
| 浏览器端请求超时(10 秒)或返回非 2xx | — | 区块错误和重试按钮 | 单元测试 |
| 客户端导航时页面 chunk 加载失败 | — | 退回整页跳转,上报"导航失败" | 没有专门的测试 |
| 页面级渲染错误 | — | 页面级错误边界,顶栏保留,上报"页面错误" | 手动:临时加一个抛错点 |
| worker 的事件循环卡死 | Watt 连续 10 次检查不健康后替换 worker | 被分到这个 worker 的请求超时 | CI 里的 Watt 验证脚本 |
| 爬虫文档超过 2MB | 记录日志并计数(不截断) | — | 单元测试 |
还有一个没有解决的问题:worker 被替换的时候,它手上还没完成的请求最终是被断开还是超时,我没有专门观察。验证脚本只看到了"被分到这个 worker 的请求在 2 秒内没有完成"。
八、测出来的数据
8.1 指标定义
这几个时间点经常被混在一起,这里分开说明:
| 指标 | 含义 | 怎么测的 |
|---|---|---|
| 首字节(TTFB) | 从发出请求到收到响应头 | 独立探针,Node http 的 'response' 事件。响应头和 shell 一起发出,所以它约等于 shell 开始到达的时间 |
| shell 到达 | 第一块数据被解压出来 | 单次请求,边下载边用 createBrotliDecompress 解压 |
| shell 完成 hydration | React 已经接管了 shell | 浏览器里,第一条帖子的 DOM 节点上出现 React fiber 的时间,从导航开始计时 |
| 文档解析完成 | 流式响应全部到达并解析完 | DOMContentLoaded |
| 完整响应时间 | 从发出请求到响应结束 | autocannon 的延迟统计 |
| ELU | 事件循环利用率(Event Loop Utilization):事件循环处于忙碌状态的时间比例,不是 CPU 使用率 | Watt 的 Prometheus 指标,每秒采样一次;"均值"是先对各 worker 求平均,再对所有样本求平均;"最大值"是单个 worker 单次采样里的最大值 |
"shell 完成 hydration"不等于"整个页面加载完成"。后面区块的数据和 hydration 还在继续,整页要等到"文档解析完成"。
8.2 结果
流式输出与压缩(本地 Node 24.22.2,单次请求,mock 的真实上游延迟:profile 头 60ms、timeline 450ms):
/ada未压缩时 32,490 字节,br 压缩后 2,800 字节,减少约 91%;- shell 在约 206ms 到达并能立即解压,帖子在约 646ms 到达,和不压缩时的时间点一致。
弱网下的 hydration(Playwright 1.65.0 的 Chromium,Node 26.13.1;Lighthouse 的 Slow 4G 配置:RTT 150ms、下行 1.6Mbps、上行 750Kbps;评论接口人为延迟 5 秒):
- 三次运行里,shell 在约 1.15 秒完成 hydration,文档在约 5.17 秒才解析完;
- X 原文同一个实验的数字是 589ms 和 6017ms,量级关系一致,但两边的环境和页面都不同,不能直接比较绝对值。
Watt 替换卡死的 worker:用调试路由同步死循环卡住一个 worker,卡死期间其他 worker 照常服务;约 10 到 11 秒后,Watt 打印 is unhealthy. Replacing it,和"每秒检查一次、连续 10 次不健康才替换"的配置对得上。
增加渲染 worker 的效果:
- 测试环境:一台共享的 8 vCPU 虚拟机(AMD EPYC 7B13),测试期间负载均值在 2 到 5 之间;Node 24.22.2;压测工具和 4 进程的 API 也在同一台机器上;
- 压测参数:autocannon 9.0,32 个并发,每轮预热 2 秒后测 10 秒,请求带
Accept-Encoding: br, gzip;上游延迟设为 0,压力全部落在渲染上; - 下表是第二次运行的结果,4 个 worker 的数据两次之间相差约 30%,但规律一致。
| worker | req/s | p50 | 首字节 p50 | ELU |
|---|---|---|---|---|
| 1 | 220 | 141ms | 38ms | 0.99(饱和) |
| 2 | 437 | 70ms | 21ms | 0.99 |
| 4 | 642 | 44ms | 21ms | 0.94 |
换成真实上游延迟后(每组同样只跑了一次 10 秒),首字节 p50 约 150ms,完整页面 p50 约 610 到 635ms。同样的流量下,每个 worker 的 ELU 从 0.32 降到 0.21 再降到 0.13,对应原文"把同样的流量分摊到更多 worker 上"那条经验。
没能复现的:假超时。 X 原文说事件循环卡顿 1.9 到 3.7 秒时,1 秒的上游超时会在响应其实已经到达的情况下先触发。我这边:
- 256 个并发下 1 个 worker 严重排队,p99 到了约 7 秒,但单次卡顿最长只有约 340 到 410ms。页面太小,延迟来自大量请求轮流排队,而不是长时间的同步阻塞;
- 把超时调到 250ms,1 个 worker 依然是 0 次;4 个 worker 反而出现了 66 次超时(其中 56 个请求失败)。当时 8 核已经超额分配,我推测是真实的 CPU 饥饿,不是假超时,没有单独验证。
这反而得到一个原文没写的教训:增加 worker 只在还有空闲核心时有效,超过之后只会增加争抢。
爬虫文档的体积:单条回复约 0.8KB,推算 500 条回复的长帖串约 0.4MB,离 X 原文说的 2MB 上限很远。回归测试模拟了"每条帖子多 5KB 内联内容",测试会失败。
九、几条可以带走的原则
- 往 React 的输出流里插内容,只在
flush()时插。write()的边界不可靠;这个钩子只有 Node 版有,选运行时之前先想清楚。 - 自定义 Transform 时,输出要在
_transform里 push。 否则Transform的背压机制会失效,慢客户端会让你把整页缓存在内存里。 - 不要在别人的流上挂
'data'监听。 只是想顺便看一眼的话,用 Transform 透传。 - 多层流用
pipeline串联,不要用pipe。pipe不传递错误。 - 压缩流式 HTML 时,每轮都要 flush 压缩器。
- 可取消性要一路贯通。 客户端断开、React
abort()、Relaydispose()、Observable 的清理函数、fetch 的AbortController,缺一环就会在服务端白白干活。 - 生产构建能掩盖开发环境的问题。 打包器对 CommonJS 的兼容处理掩盖了一个纯类型 import,两个环境要分别测。
- 自定义分块之后,要检查入口文件到底执行了什么。 入口模块被收进共享 chunk,多个入口的代码会一起执行。
- 流式 SSR 下,状态码 200 不代表没有降级。 要单独观测,服务端日志和浏览器上报都要有。
- 因人而异的 HTML 要显式禁止共享缓存。 每个响应都可能带着不同的
Set-Cookie,只设Vary是不够的,要明确写Cache-Control: private, no-store。
这些结论都有对应的测试:背压是"300 个区块写进不读的下游",丢字节是"晚 20ms 才开始读的消费者",转义是"内容本身就是 </script> 的回复",重复 hydrate 是"检查每个入口文件调用的 boot()"。如果你也在做流式 SSR,比起照搬某种架构,更值得做的是把这几种情况各写一个测试,看看自己的实现能不能过。
实验场里还有不少这篇没展开的东西:SEO 对比、persisted queries、负载测试的完整数据。都记在仓库的 ARCHITECTURE.md 里。
附录 A:启动分块的产物
7dfaa23 的生产构建,未登录入口启动时要加载的文件(大小单位是字节):
| 文件 | 原始 | gzip | brotli | 内容 |
|---|---|---|---|---|
startup-deps | 482,148 | 134,886 | 113,650 | 启动时用到的所有 node_modules:React、react-dom、Relay |
startup-app | 24,675 | 7,526 | 6,595 | 启动时用到的自有代码 |
styles(JS) | 1,615 | 828 | 713 | Vite 的预加载辅助函数 |
startup-names | 914 | 426 | 388 | 懒加载 chunk 的文件名映射,只有动态 import |
rolldown-runtime | 237 | 196 | 156 | Rolldown 的运行时 |
logged-out(入口) | 52 | 72 | 56 | 只有一行:import { t as e } from "./startup-app-….js"; e(!1) |
styles.css | 685 | 362 | 266 | 样式 |
加起来是 6 个 JS 文件和 1 个 CSS 文件。各页面的懒加载 chunk 在 0.5KB 到 1.3KB 之间。
这里有一个能说明为什么要单独拆出 startup-deps 的细节:它的文件名哈希是 DX9X52dl,和最早修好分块那次构建时一模一样。之后几十次业务代码的改动,都没有让这个 113KB 的依赖文件缓存失效。
附录 B:几段真实的测试代码
背压(apps/web/src/ssr/backpressure.test.ts):渲染 300 个各 5000 字节的区块,下游先不读,统计 React 写进注入器的字节数。
const stream = renderToPipeableStream(bigPage(), {
onShellReady() {
stream.pipe(injector)
},
})
// Nobody reads: React must stop after roughly the stream's buffer size,
// not write the full page into memory.
await settle()
const writtenWhileStalled = written
expect(writtenWhileStalled).toBeLessThan((BOUNDARIES * BOUNDARY_BYTES) / 4)
// The reader catches up: everything arrives, complete.
let html = ''
for await (const chunk of injector) html += chunk
expect(html.endsWith('</body></html>')).toBe(true)
expect(html.match(/<p id="p\d+">/g)?.length).toBe(BOUNDARIES)CSP nonce(apps/web/src/ssr/render.test.ts):用真实的路由和 mock 数据调用真实的 render(),把 HTML 解析成 DOM 后检查每一段可执行脚本。JSON 数据块不会被执行,不在检查范围内。
const DATA_TYPES = ['application/json', 'application/ld+json']
const isExecutable = (el: El) => el.name === 'script' && !DATA_TYPES.includes(el.attrs.type ?? '')
it('puts the nonce on every executable script: ours, the stream injector, and React', async () => {
const nonce = 'n0nce+/='
const { html } = await renderHtml('/ada/status/1001', { nonce })
const scripts = parse(html).filter(isExecutable)
// replay registry, loader, at least one __rr.p() and React's streaming script
expect(scripts.length).toBeGreaterThanOrEqual(4)
for (const s of scripts) expect(s.attrs.nonce, s.text.slice(0, 40)).toBe(nonce)
})入口只执行自己的 boot()(apps/web/tests/bundle.test.ts):检查构建产物,防止 5.6 ③ 的问题复发。压缩后 boot(false) 变成了 (!1)。
it('each entry runs only its own boot()', () => {
const loggedOut = read(manifest['src/entries/logged-out.tsx'].file)
const signedIn = read(manifest['src/entries/signed-in.tsx'].file)
expect(loggedOut).toMatch(/\(!1\)/)
expect(loggedOut).not.toMatch(/\(!0\)/)
expect(signedIn).toMatch(/\(!0\)/)
expect(signedIn).not.toMatch(/\(!1\)/)
})附录 C:复现
git clone https://github.com/wuchendi/x-ssr-reconstruct && cd x-ssr-reconstruct
git checkout 7dfaa23
pnpm install
pnpm turbo run build typecheck test # 构建、类型检查、137 个单元测试
node apps/web/scripts/watt-stall-check.mjs # Watt 替换卡死的 worker
# SEO 对比和浏览器检查需要先启动三个服务
REPLIES_LATENCY_MS=5000 DEBUG_FAILURES=1 PORT=3302 node apps/api/src/main.ts &
UPSTREAM_TIMEOUT_MS=10000 DEBUG_FAILURES=1 PORT=3300 node apps/web/server/main.ts &
PORT=3301 node apps/legacy-ssr/src/server.ts &
pnpm parity # 11 个路径
BASE=http://127.0.0.1:3300 DEBUG_FAILURES=1 pnpm e2e:browser # 29 项,需要安装 Playwright 的 Chromium
node apps/web/scripts/load-test.mjs # 负载测试,需要 Linux(读取 /proc)