Chendi Wu
Chendi WuMediaPhotographyProjectsBlog
Back to blog

从 X 的 SSR 架构出发:React 流式渲染与 Node.js Stream 的工程深挖

以 X 重写 x.com 的 SSR 架构为出发点,做了一个可运行的实验场。真正的收获不是复刻出的三类访问者,而是挖出来的 React、Node.js、Relay、Rolldown 之间不容易被发现的交互问题,以及数据、资源、故障在流式 SSR 里的完整生命周期。

Published2026-11-12
NotesReactSSRNode.js

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-dom19.3.1
Relay(react-relay / relay-runtime / relay-compiler)21.0.1
Vite / Rolldown8.3.7 / 1.2.18
Fastify5.12.8
Platformatic Watt3.78.0
TypeScript / Vitest7.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
  1. 边缘层判断访问者类型(实验场里用请求头模拟)。
  2. Fastify 为这个请求生成 CSP nonce;带尾部标点的 URL 在这里直接 301。
  3. guest token 和 feature flags 并行请求。两者之间没有依赖,原文专门提到过:以前要等 guest token 回来才去请求 flags,白白多了一个串行往返。
  4. 匹配路由,静态路径优先于动态参数。
  5. loader 发出这个路由的全部查询。预览 bot 是例外:它只发首屏查询,见第三节。
  6. 并行等两样东西:页面 chunk 和首屏查询。 拿到后确定状态码和 <head>。
  7. React 开始渲染(renderToPipeableStream),shell 一好就开始输出,这就是首字节。
  8. 每个查询的响应到达后,交给注入器暂存,在下一个 flush 点写进页面,排在渲染它的区块前面。
  9. 输出依次经过压缩和 socket。爬虫文档在压缩之前还要统计一次字节数。
  10. 浏览器端:先执行回放注册表脚本,再加载 CSS,CSS 加载完成后才加载 async 入口;入口执行后 hydrateRoot,shell 先 hydrate,后面每个区块在它的 HTML 和数据都到齐之后再 hydrate。
  11. DOMContentLoaded:流式响应全部到达并解析完。注册表标记"流已结束",还在等待的查询改为请求 API;没人取走的响应保留 30 秒后清掉。
  12. 服务端 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 不做缓冲随请求结束被回收
各个查询的 PreloadedQueryloader 发出查询时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-Controlprivate, no-storeprivate, no-storeprivate, 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 后浏览器端恢复耗时
/ada6,270 字节7,360 字节1.17×495 vs 771 字节回放 322µs,恢复 Store 52µs
/ada/status/10015,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,以及几个页面 chunkstartup-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 完成 hydrationReact 已经接管了 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%,但规律一致。
workerreq/sp50首字节 p50ELU
1220141ms38ms0.99(饱和)
243770ms21ms0.99
464244ms21ms0.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 内联内容",测试会失败。

九、几条可以带走的原则

  1. 往 React 的输出流里插内容,只在 flush() 时插。 write() 的边界不可靠;这个钩子只有 Node 版有,选运行时之前先想清楚。
  2. 自定义 Transform 时,输出要在 _transform 里 push。 否则 Transform 的背压机制会失效,慢客户端会让你把整页缓存在内存里。
  3. 不要在别人的流上挂 'data' 监听。 只是想顺便看一眼的话,用 Transform 透传。
  4. 多层流用 pipeline 串联,不要用 pipe。 pipe 不传递错误。
  5. 压缩流式 HTML 时,每轮都要 flush 压缩器。
  6. 可取消性要一路贯通。 客户端断开、React abort()、Relay dispose()、Observable 的清理函数、fetch 的 AbortController,缺一环就会在服务端白白干活。
  7. 生产构建能掩盖开发环境的问题。 打包器对 CommonJS 的兼容处理掩盖了一个纯类型 import,两个环境要分别测。
  8. 自定义分块之后,要检查入口文件到底执行了什么。 入口模块被收进共享 chunk,多个入口的代码会一起执行。
  9. 流式 SSR 下,状态码 200 不代表没有降级。 要单独观测,服务端日志和浏览器上报都要有。
  10. 因人而异的 HTML 要显式禁止共享缓存。 每个响应都可能带着不同的 Set-Cookie,只设 Vary 是不够的,要明确写 Cache-Control: private, no-store。

这些结论都有对应的测试:背压是"300 个区块写进不读的下游",丢字节是"晚 20ms 才开始读的消费者",转义是"内容本身就是 </script> 的回复",重复 hydrate 是"检查每个入口文件调用的 boot()"。如果你也在做流式 SSR,比起照搬某种架构,更值得做的是把这几种情况各写一个测试,看看自己的实现能不能过。

实验场里还有不少这篇没展开的东西:SEO 对比、persisted queries、负载测试的完整数据。都记在仓库的 ARCHITECTURE.md 里。

附录 A:启动分块的产物

7dfaa23 的生产构建,未登录入口启动时要加载的文件(大小单位是字节):

文件原始gzipbrotli内容
startup-deps482,148134,886113,650启动时用到的所有 node_modules:React、react-dom、Relay
startup-app24,6757,5266,595启动时用到的自有代码
styles(JS)1,615828713Vite 的预加载辅助函数
startup-names914426388懒加载 chunk 的文件名映射,只有动态 import
rolldown-runtime237196156Rolldown 的运行时
logged-out(入口)527256只有一行:import { t as e } from "./startup-app-….js"; e(!1)
styles.css685362266样式

加起来是 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)
Copyright (c) 2023-PRESENT All Rights Reserved. Powered by wudi