去年做过一个商品详情页,上了服务端渲染。上线后客服转来一类反馈:页面打开挺快的,内容立刻就在,但点「加入购物车」没反应,要等一两秒才突然变正常。开发机上完全感觉不到,因为本地的 JS 几十毫秒就执行完了。

这就是服务端渲染最容易让人误解的地方:它优化的是「看到内容」的时间,不是「能操作」的时间。HTML 先到,浏览器先把内容画出来;JavaScript 后到,框架再把这份已经存在的 DOM 接管过来,挂上事件、恢复状态。中间这段空窗期,页面看起来是好的,实际是个不能点的静态图。

这篇要讲的就是这段空窗期:它叫什么、里面发生了什么、为什么会有「服务端和客户端渲染结果不一致」的警告,以及 SSR、SSG、流式渲染、岛屿架构这些方案各自在拿什么换什么。先从一个能稳定复现的观察开始。

把「有内容但不能点」复现出来

不需要完整框架,一个最小例子就够了。服务端把组件渲染成字符串,客户端用水合接管:

// server.js
import express from "express";
import { renderToString } from "react-dom/server";
import App from "./App.js";

app.get("/", (req, res) => {
  const html = renderToString(<App />);
  res.send(`<!doctype html>
    <div id="root">${html}</div>
    <script src="/client.js"></script>`);
});

// client.js
import { hydrateRoot } from "react-dom/client";
import App from "./App.js";

hydrateRoot(document.getElementById("root"), <App />);

页面里的 App 放一个计数按钮。然后用 Chrome DevTools 的 Network 面板限速到 Slow 3G,刷新。你会看到:标题、按钮的文字几乎是立刻出现的(HTML 到达就画),但点按钮没有任何反应;等 client.js 下载并执行完,按钮突然开始工作。

接下来验证三个可能的解释:

是不是服务端渲染太慢? 看 Network 里 HTML 的响应时间。如果 HTML 很快就回来了,说明瓶颈不在这里。

是不是 JS 下载太慢? 把限速去掉,按钮还是有一段延迟,只是短了。说明下载不是唯一原因,执行本身也要花时间。

是不是框架把整页重新渲染了一遍? 在 Elements 面板里选中按钮,打开「保留日志」,观察水合前后这个 DOM 节点有没有被替换。没有替换,说明它确实复用了服务端产出的 DOM。

结论是第三种解释更接近:水合不是重新渲染,而是在已有 DOM 上重建内部的组件树、核对结构、绑定事件。DOM 没重建,但「让它能响应」这件事本身要花时间。

一次 SSR 请求,完整链路是这样的

从请求到可交互
服务端渲染执行组件,产出 HTML 字符串或流
浏览器解析边收边解析,CSS 到位后先画出首屏
下载与执行 JS框架、业务代码、数据都要到齐
水合复用 DOM,建组件树,绑定事件
可交互点击、输入、路由切换开始生效

这几个阶段对应几个不同的指标。首字节时间衡量服务端多快开始响应;首次内容绘制衡量用户多快看到东西;可交互时间衡量页面多快能真正用。SSR 明显改善前两个,对第三个的帮助取决于 JS 的体积和水合的成本,弄不好反而更差,因为客户端还是要执行一遍完整的组件树。

很多人把 SSR 当成「把渲染挪到服务器,客户端就省事了」。实际不是:服务端产出 HTML 只是让首屏早点出现,客户端仍然要把同一套组件再跑一遍,才能把交互接上。省掉的是「等待 JS 才能看到内容」,不是「执行 JS」。

水合具体在做什么

以 React 18 为例,hydrateRoot 拿到容器和组件树之后,做的是这些事:

  • 遍历服务端已经生成的 DOM,和组件返回的元素逐一对应,建立内部的 Fiber 树;
  • 核对类型、层级、文本内容是否一致,不一致就记录为 mismatch;
  • 把事件监听挂到根容器上(React 用的是事件委托,不是给每个节点单独绑定);
  • 执行布局阶段的副作用和普通副作用,恢复组件里那些「挂载后要做的事」;
  • 对于 Suspense 边界,可以延后处理,先让其他部分可用。

所以水合的成本和组件树的大小强相关,而不是和 DOM 节点数简单成正比。一个包裹了很多逻辑、返回很少 DOM 的组件,照样要在客户端执行一遍。纯展示的长列表,DOM 节点多,但组件逻辑简单,水合反而可能更快。

React 18 的 hydrateRoot 和旧的 hydrate 不是同一个东西。前者接入了并发渲染和选择性水合,后者在 18 里已被标记为旧 API。写新代码时别再从 react-dom 里找 hydrate。

水合完成后,页面才进入正常的客户端渲染状态。之后每次状态更新走的都是普通的更新流程,和纯客户端应用没有区别。这也是为什么水合阶段的性能问题容易被忽略:它只在首屏发生一次,但每个用户每次刷新都要付一遍。

为什么会有 mismatch

React 会在开发环境打印类似这样的警告:

Warning: Text content did not match. Server: "10:32" Client: "10:33"

它的意思是:服务端渲染出的某个文本是「10:32」,客户端在同一个位置算出来的是「10:33」。React 没法确定谁对,只能按客户端的来,并把这一段重新渲染。问题不在框架,在于同一段代码在两边拿到了不同的输入。

常见的输入差异有这么几类:

时间和随机

服务端渲染的瞬间和客户端水合的瞬间不是同一时刻,new Date()、Math.random()、相对时间(「3 分钟前」)都会对不上。时区和语言设置也可能不同。

环境差异

服务端没有 window、localStorage、navigator。代码里判断 typeof window 后再渲染不同内容,两边必然不一致。用户本地保存的主题、登录态也属于这一类。

数据不一致

服务端用请求里的 cookie 取了一份数据,客户端挂载后又按自己的方式取了一份,两份不同步。或者服务端拿到的是缓存里的旧数据。

HTML 结构非法

比如在 p 里放 div,浏览器解析时会自动纠正结构,客户端按源码结构去对应,自然对不上。这类问题不看浏览器纠正规则很难发现。

解决办法不是「关掉警告」,而是让两边在首次渲染时拿到同样的输入。时间相关的展示,服务端先渲染一个占位,等客户端挂载后再用 useEffect 更新;本地状态相关的部分,等挂载后再渲染;数据用同一份序列化结果传给客户端,别让它自己再请求一次。

React 18 在遇到 mismatch 时,会先尝试修补能对上的部分;遇到结构性问题,则可能放弃复用、退回客户端渲染。这两种情况都会在控制台给出提示。后者比整页重建好一些,但也意味着问题可能被「修好」得悄无声息:页面看起来正常,只是多了一次渲染,性能账单在低端机上才显形。

流式与选择性水合

传统 SSR 用 renderToString,要等整棵树渲染完才发出完整 HTML。如果某个区块的数据慢,整页都得等。React 18 提供的 renderToPipeableStream(Node 环境)和 renderToReadableStream(支持 Web Streams 的运行时)改变了这一点:先把能渲染的部分(通常叫 shell)发出去,遇到 Suspense 边界就先发占位,等异步数据好了再把补丁流式追加。

const stream = renderToPipeableStream(<App />, {
  bootstrapScripts: ["/client.js"],
  onShellReady() { stream.pipe(res); },
  onShellError(err) { res.statusCode = 500; res.end("出错了"); },
});

浏览器收到前者就能先画,HTML 是分块到达的,Network 面板里能看到响应体一点点变长。用户更早看到内容,但页面结构会随着补丁到达而变化,布局可能抖一下。对于重要区块,还是要在首屏 shell 里给出稳定的骨架,避免内容到达时把下面的东西推走。

选择性水合是另一半。React 18 会按 Suspense 边界把水合拆成多个单元,先水合已经就绪的部分;还没就绪的边界可以先不处理。用户在某个未水合的边界里点了按钮,React 会先把事件记下来,等这个边界水合完成后再重放。这就是为什么流式页面里,某些区域看起来「慢半拍」才响应,而不是彻底没反应。

代价是实现复杂度上升:你要设计 Suspense 的粒度,处理服务端已经发出去之后才发生的错误,还要考虑缓存和 CDN 能不能存这种分块的响应。它不是一个开关,是一套需要和路由、数据层一起设计的机制。

几种渲染模式,各自在换什么

纯客户端渲染HTML 基本是空壳,所有内容靠 JS 生成。服务器压力最小,部署最简单;首屏最慢,SEO 和弱网体验最差。
服务端渲染每次请求在服务端执行组件,返回完整 HTML。首屏快,动态内容友好;服务器成本和缓存复杂度都上来了。
静态生成构建时把页面渲染成 HTML,部署成静态文件。最快、最便宜;内容更新要重新构建,个性化内容做不了。
增量再生成静态页面按策略在后台重新生成,兼顾速度和新鲜度。策略调不好会出现「刚改完还是旧内容」。
岛屿架构页面主体是静态 HTML,只有需要交互的组件单独加载并水合。JS 量最小;跨岛屿共享状态和整体路由要额外设计。

还有一类思路叫可恢复性,代表是 Qwik:把状态和事件处理函数序列化进 HTML,客户端不重新执行整棵组件树,而是从断点「恢复」。它解决的是水合成本本身,但对序列化的要求很高,生态和调试方式都和传统框架不同。具体实现细节随版本变化,这里只讲思路,不展开。

选型的顺序应该是:先问这个页面需不需要 SEO 和首屏内容,再问内容是否允许提前生成,最后问交互占多大比例。内容型页面用静态生成加少量岛屿,通常比整页 SSR 更划算;后台系统根本不需要 SEO,纯客户端渲染最省事。为了「技术先进」给内部管理系统上 SSR,是典型的负收益。

现象、机制、怎么自己验证

现象真实机制怎么验证
首屏内容立刻出现,按钮过一会儿才能点 HTML 到达即绘制,事件绑定要等 JS 下载、执行、水合完成 Slow 3G 下刷新,同时用 Performance 面板看水合区间的耗时
控制台报 Text content did not match 服务端和客户端首次渲染拿到了不同输入,比如时间、随机数、本地状态 按警告里的两段文本定位组件,把动态值改成挂载后更新再刷新
水合后页面闪一下,局部 DOM 被替换 mismatch 导致 React 放弃复用那棵子树,改为客户端重新渲染 Elements 面板开启保留日志,观察该节点是否被移除再插入
同一个接口在 Network 里出现两次 服务端预取的数据没有序列化给客户端,客户端挂载后又请求了一次 看两次请求的发起者,把首屏数据写进内联脚本再对比请求数
禁用 JS 后页面有内容,但所有交互失效 服务端只产出了 HTML 和样式,事件绑定与水合都在客户端 DevTools 设置里禁用 JavaScript 后刷新,判断哪些内容是服务端产出的
流式页面分块出现,内容逐渐补齐 Suspense 边界按块到达,浏览器边解析边渲染,后到的补丁替换占位 Network 里看 HTML 响应体是否逐步增长;观察占位是否被替换
静态页面内容过期,接口已经是新数据 HTML 是构建时生成的,数据变化后没有触发重新生成 对比 HTML 源码里的时间戳和接口返回值,确认生成时间

边界与代价

服务器成本是实打实的。 SSR 把渲染从每个用户的设备挪到了你的机器上,并发一高就是 CPU 和内存账单。缓存能缓解,但一旦页面和用户相关,缓存键就要带上用户维度,命中率会掉得很快。很多团队最后发现,把最容易缓存的静态部分做成静态页,只对少量个性化区块做动态渲染,比整页 SSR 便宜得多。

水合成本会被低估。 大家盯的都是 JS 体积,实际还要看执行时间。同一份代码在开发机上几十毫秒,在中低端手机上可能是几倍。真正要优化的是「首屏到底需要水合多少东西」,而不是一味压体积。岛屿架构和选择性水合都是在这个方向上做减法。

流式渲染的错误处理更麻烦。 响应头已经发出去、状态码已经定了,后面某个区块才出错,你没法再改成 500。只能靠错误边界在页面内降级,并且保证降级后的页面仍然可用。设计时要先想清楚「哪块失败了可以没有,哪块失败必须整页报错」。

个性化与缓存天然冲突。 带用户信息的页面不能直接放进公共 CDN 缓存,按用户做缓存又容易打穿。边缘渲染是一个折中:把渲染放到离用户近的节点,缓存仍然按地理位置和用户维度算。它增加了部署复杂度,也受运行时能力限制。

服务端环境不是浏览器。 任何在模块顶层碰 window、document、localStorage 的第三方库,都会在服务端直接崩。导入时就要判断,或者把这类组件放到客户端再加载。这个坑在引入图表库、地图库、编辑器时尤其常见。

把数据序列化进 HTML 有安全边界。 服务端把状态写进 <script> 时,必须正确转义 <、& 和引号,否则用户输入里的 </script> 就能提前闭合标签,变成 XSS。用框架提供的序列化工具,别自己拼字符串。

静态生成不是免费的。 页面数量一多,构建时间会线性增长;内容频繁变化时,重新构建的成本和发布流程都会变重。增量再生成缓解了这一点,但引入了「什么时候算过期」的新问题,缓存策略写错就会出现用户看到旧价格的情况。

今天就能动手的实验

  1. 搭一个最小的 React SSR 例子,用 renderToString 加 hydrateRoot,先在正常网络下点按钮,再把 Network 限速到 Slow 3G,记录「看到内容」和「能点击」之间的时间差。
  2. 在组件里放一个 new Date().toLocaleTimeString(),刷新几次,观察控制台的 mismatch 警告;改成挂载后再更新,警告消失。
  3. 禁用 JavaScript 刷新 SSR 页面,确认首屏内容还在;再禁用后再点按钮,理解「内容」和「交互」是两件事。
  4. 把 renderToString 换成 renderToPipeableStream,在 Network 面板里观察 HTML 响应体是不是分块到达的。
  5. 把首屏接口数据序列化进页面,客户端直接读取,比较 Network 里接口请求从两次变成一次前后的差异。

小结

SSR 优化的是「看到内容」的时间,不是「能操作」的时间。HTML 先到只是让首屏出现得更早,交互仍然要等 JS 执行完。
水合是复用已有 DOM、重建组件树、绑定事件的过程,成本跟组件树的复杂度走,不只是 DOM 数量。
mismatch 的根因是服务端和客户端首次渲染的输入不同。时间、随机数、本地状态、非法 HTML 结构都是常见来源。
没有一种渲染模式全面占优。静态生成适合内容页,客户端渲染适合后台,SSR 适合动态且需要首屏的页面,岛屿架构适合交互稀少的页面。

下一篇讲React 渲染机制。水合只是把组件树接管过来,接管之后每一次状态变化,React 都要决定「更新哪棵子树、什么时候提交到 DOM、能不能中途打断」,这套机制才是日常开发里最常撞上的部分。为什么 setState 之后立刻打印还是旧值、为什么改了对象页面没动,都会在下一篇里找到答案。