在 `SSR` 体系里，用户拿到的首屏内容往往是一段已经“长得像页面”的 `HTML`。它能被浏览器立刻解析成 `DOM` 并绘制到屏幕上，但此时页面依然像一张“干的照片”：看得到，却不一定点得动。`hydration` 的任务，就是把这张静态快照变成真正能响应交互的应用，把组件逻辑、事件处理、状态管理接回到浏览器端运行。React 文档用非常直白的措辞描述了这件事：`hydration` 会把组件逻辑“附着”到服务端生成的初始 `HTML` 上，让它变成可交互的应用。([React][1])

为了把 `hydration` 讲透，下面我会用“浏览器真实发生了什么”的视角，把它拆成几个层次：网络与解析层、框架运行时层、事件系统层、状态与副作用层、异常与性能层。阅读时你会发现，`hydration` 并不是一个单一动作，更像一串精密的对齐与接管流程。

---

## 一、`hydration` 出现的前提：你已经做了 `SSR`，并且准备在客户端再跑一遍框架

把典型的 `SSR + hydration` 请求路径压缩成一句话：

> 服务端把 UI 渲染成 `HTML` 发给浏览器，浏览器先显示出来；客户端脚本加载后，框架在同一棵 `DOM` 上建立内部数据结构与事件系统，尽量复用现有节点并接管后续更新。

web.dev 在讨论 `server-side rendering with rehydration` 时强调了一个关键事实：页面可能“看起来已经加载完成”，但在组件脚本执行、事件处理器真正挂载之前，它并不能响应输入，这会让用户非常困惑。([web.dev][2])

这句话其实点出了 `hydration` 的核心矛盾：**要快**（先把内容给用户看到），也要**真**（最终必须变成可交互应用）。把这两件事拼起来，就需要一段“接管期”，而 `hydration` 就是这段接管期的名字。

---

## 二、从时间线看 `hydration`：浏览器里按顺序发生的事情

下面这条时间线非常贴近你在 `Chrome DevTools` 里看到的真实顺序：

### 1）浏览器拿到服务端返回的 `HTML`，立刻解析并绘制

* 网络层收到 `document` 响应
* `HTML parser` 流式解析，边解析边构建 `DOM`
* 如果遇到 `link rel=stylesheet`，会触发 `CSS` 下载与解析
* `DOM + CSSOM` 形成渲染树，进入 `layout`、`paint`、`composite`

这一段与任何传统多页站点没有本质差异，也是 `SSR` 能让 `FCP` 更快的根源：浏览器不需要等大段 `JavaScript` 执行才有内容可画。([web.dev][2])

### 2）浏览器下载并执行客户端 `JavaScript`，框架运行时启动

当 `React`、`Next.js` 或其他框架的客户端包开始执行，`hydration` 才真正进入舞台。以 React 为例，客户端会调用 `hydrateRoot(container, <App />)`，告诉 React：`container` 里已经有服务端渲染的 `HTML`，请不要像纯 `CSR` 那样整棵重建，而是进入 `hydration` 模式去复用与对齐。([React][1])

### 3）框架把“组件树”与“现有 DOM”对齐，建立内部结构并挂上事件

这一步是 `hydration` 的技术核心：不是简单地 `addEventListener`，也不是简单地重新渲染，而是**在已有 `DOM` 上建立一套可更新的内部表示**（React 里对应 `Fiber tree`），同时把事件系统、状态、更新调度都接上。

只要这一步完成，页面从“能看”进入“能用”。

---

## 三、`hydration` 的内核动作拆解：对齐、复用、接管

把 `hydration` 想象成“接管一座已经建好的房子”。服务端把墙和门都盖好了（`HTML`），但电路与智能系统还没装（事件、状态、更新）。客户端要做的事，是在不拆房子的前提下，把电路一点点接进去，并确认每个开关对应的灯确实在那个位置。

下面按内部动作拆开讲。

### 动作 A：创建 `root` 与运行时上下文，进入 `hydration` 模式

React 的入口是 `hydrateRoot`。它和 `createRoot` 很像，但语义不同：`hydrateRoot` 明确告诉 React 容器里已有由 `ReactDOMServer` 生成的 `HTML`，需要“附着”逻辑而不是重绘。([React][1])

这一步会建立一组非常关键的运行时对象：

* 根容器与调度器（后续更新怎么排队、怎么分片、怎么中断与恢复）
* 事件系统的入口（合成事件、委托、优先级）
* 将要构建的组件内部树（React 是 `Fiber`）

你可以把它理解成：框架在浏览器里先搭一个“指挥部”。

### 动作 B：在客户端“再渲染一次组件树”，但目标不是生成新 DOM，而是生成“期望的结构”

很多人听到“再渲染一次”会以为重复浪费。事实是：客户端必须生成一份“我认为页面应该长什么样”的描述，否则它无法验证服务端给的 `HTML` 是否匹配，也无法建立从组件到真实节点的映射关系。

以 React 为例，客户端会执行组件函数，得到虚拟树；接着进入 `hydration reconciliation`：拿虚拟树的节点与已有 `DOM` 节点做逐个匹配。

这也是为什么 `hydration` 对一致性极度敏感：服务端渲染出来的结构，必须与客户端首轮渲染的结构一致，否则匹配会失败，框架只能报警甚至局部放弃复用。

### 动作 C：DOM 节点复用与“绑定关系”建立

匹配成功时，框架会做两类绑定：

* **从组件节点到真实 DOM 的引用绑定**：以后组件更新时知道该改哪个真实节点
* **从真实 DOM 到组件实例的反向关联**：事件冒泡上来时，能从目标节点追溯到对应的组件监听器

这一步在工程上非常关键：它决定了后续更新是不是 `diff` 级别的增量修改，而不是整棵替换。

Gatsby 的文档在解释 React `hydration` 时也提到，React 会尝试在现有标记上附加事件监听器，让站点从静态 `HTML` 转为完整 React 应用。([Gatsby][3])

### 动作 D：事件系统接管：你以为是给按钮绑 `onClick`，实际常常是“根节点委托 + 运行时分发”

很多现代框架不会给每个按钮都单独 `addEventListener`。React 的合成事件系统通常采用事件委托：在根容器上挂少量监听器，事件触发时通过运行时逻辑找到对应组件的回调并执行。

`hydration` 阶段的意义在于：**把这些回调的映射关系建好**。服务端输出的 `HTML` 里不可能包含真实的函数引用，因此按钮看起来存在，但点击时没有任何 JS 逻辑能跑。`hydration` 完成后，事件系统才知道这个 `<button>` 对应组件树里的哪个 `onClick`。

web.dev 那句“看起来可交互但实际上不能响应输入，直到事件处理器被附着”说的就是这件事。([web.dev][2])

### 动作 E：状态初始化与一次性数据对齐

如果页面包含状态（例如购物车数量、登录用户信息），服务端渲染时用到的数据需要在客户端也能拿到，否则客户端首轮渲染就会“长得不一样”。

真实项目里常见做法是：

* 服务端把初始数据序列化到页面中（例如挂在 `window.__INITIAL_DATA__`）
* 客户端启动时读取该数据，用它作为首轮渲染的数据源

只要两边用的是同一份数据，组件树结构就更容易一致，`hydration` 更稳定。

### 动作 F：副作用与布局相关逻辑的时机差异

在 React 中，`useEffect` 与 `useLayoutEffect` 的执行时机不同。`hydration` 期间，框架通常会尽量避免破坏已存在的 DOM 结构，但副作用仍然会在合适时机触发：

* 布局相关的副作用（例如测量元素尺寸）若执行过早，可能造成抖动
* 数据拉取副作用若不做去重，可能导致“服务端拉一次、客户端再拉一次”

这也是 `SSR + hydration` 容易踩到的工程坑：你既想利用服务端提前拿数据，又不想在客户端重复成本。

---

## 四、一个最小可运行的例子：同一颗按钮，服务端能渲染，客户端才能点击

下面用最小 React `SSR + hydration` 例子把抽象流程具体化。这个例子刻意保持简洁：服务端返回一个带按钮的 `HTML`，按钮文字可见；客户端 `hydrateRoot` 之后按钮才真正可点。

> 说明：示例代码使用单引号与反引号，避免出现英文双引号。

### 1）server.js：服务端渲染出 `HTML`

```js
// server.js
import express from 'express'
import React from 'react'
import { renderToString } from 'react-dom/server'
import App from './src/App.js'

const app = express()
app.use('/static', express.static('static'))

app.get('/', (req, res) => {
  const html = renderToString(React.createElement(App, { initialCount: 1 }))

  res.send(`<!doctype html>
<html lang='zh'>
  <head>
    <meta charset='utf-8' />
    <meta name='viewport' content='width=device-width, initial-scale=1' />
    <title>SSR with hydration demo</title>
  </head>
  <body>
    <div id='root'>${html}</div>

    <script>
      window.__INITIAL_PROPS__ = { initialCount: 1 }
    </script>
    <script type='module' src='/static/client.js'></script>
  </body>
</html>`)
})

app.listen(3000, () => {
  console.log('listening on http://localhost:3000')
})
```

### 2）src/App.js：组件里有交互逻辑

```js
// src/App.js
import React, { useState } from 'react'

export default function App(props) {
  const [count, setCount] = useState(props.initialCount ?? 0)

  return (
    React.createElement('div', null,
      React.createElement('p', null, `当前 count：${count}`),
      React.createElement('button', { onClick: () => setCount(count + 1) }, '点我 +1')
    )
  )
}
```

### 3）static/client.js：客户端做 `hydrateRoot`

```js
// static/client.js
import React from 'react'
import { hydrateRoot } from 'react-dom/client'
import App from '../src/App.js'

const props = window.__INITIAL_PROPS__ ?? { initialCount: 0 }

hydrateRoot(
  document.getElementById('root'),
  React.createElement(App, props)
)
```

这个例子里，有一个极容易验证的现象：

* 服务端返回后，`HTML` 里已经有 `button` 与 `p`，用户立刻能看到 `当前 count：1`
* 在客户端脚本还没加载完之前，点击按钮不会触发 `setCount`
* 当 `hydrateRoot` 运行并完成对齐后，按钮点击才会生效

这正对应 React 文档的定义：`hydration` 会把组件逻辑附着到服务端生成的 `HTML` 上，让快照变成交互式应用。([React][1])

---

## 五、为什么会出现 `hydration mismatch`：对齐失败时框架到底在抱怨什么

`hydration mismatch` 的本质非常朴素：**客户端首轮渲染出来的“期望结构”与服务端给的 `HTML` 不一致**。Next.js 专门有一页文档解释 `react hydration error`，并给出常见原因与处理方式。([Next.js][4])

### 常见触发源：时间、随机数、地区格式、仅客户端信息

这类问题的共同点是：服务端与客户端在首轮渲染时得到的值不同。

* 服务端渲染 `Date.now()`，客户端渲染时刻已经变了
* 服务端渲染 `Math.random()`，客户端永远不可能一致
* 服务端按 `en-US` 格式化数字，客户端按用户浏览器语言格式化
* 服务端拿不到 `window.innerWidth`，客户端拿得到

一旦这些差异影响了文本内容、属性值、节点结构，React 在 `hydration` 时就会发现对不上，进而报错或回退到更保守的策略（例如丢弃某段复用，重新生成）。

### 一个真实可感知的例子：商品页的 `倒计时` 与 `库存跳动`

电商详情页经常有 `倒计时`、`实时库存`、`实时在线人数`。如果你在服务端把 `倒计时剩余秒数` 直接写进 `HTML`，客户端启动时可能已经过了几秒。哪怕只差 1 秒，文本都不一致，就会触发 `hydration mismatch`。

Next.js 文档给出了一种“确实不可避免时”的处理方式：对某些元素使用 `suppressHydrationWarning` 来抑制警告，例如时间戳这种天然会变的内容。([Next.js][4])

更工程化的做法是把这类内容改为“客户端接管后再更新”：

* 服务端输出一个稳定占位值，确保结构一致
* 客户端在 `useEffect` 里启动定时器更新文本

这样牺牲了几秒的准确性，却换来 `hydration` 的稳定与更少的回退成本。

---

## 六、性能视角：`hydration` 为什么会伤 `INP` 与 `TBT`，以及怎么缓解

很多团队做 `SSR` 是为了更快的首屏内容展示，但如果 `hydration` 代价过高，页面会陷入一种“看起来好了，点起来卡”的状态。web.dev 明确指出：带 `rehydration` 的 `SSR` 可能显著负面影响 `TBT` 与 `INP`，即使它改善了 `FCP`。([web.dev][2])

这里的机制很清晰：

* `hydration` 需要下载、解析、执行客户端脚本
* 需要遍历并匹配现有 `DOM`
* 需要建立组件内部结构、事件映射、调度器
* 需要运行部分副作用与布局相关逻辑

这些都压在浏览器主线程上，主线程忙时用户的输入无法及时被处理，`INP` 就会变差。

### 一个很有代表性的行业案例：选择性 `hydration` 与 `Suspense`

Vercel 在介绍 `React 18` 与 `Suspense` 时提到，他们在 nextjs.org 上通过选择性 `hydration` 等手段把 `TBT` 从 430 ms 降到 80 ms，并同时验证了对交互指标的改善。([Vercel][5])

这类优化思路的核心是：**别把整页一次性都水合**。用户真正要点的通常是首屏按钮、菜单、搜索框；页脚、推荐列表、复杂图表可以延后。

### 渐进式 `hydration`：把接管拆成块

patterns.dev 把这类思路总结为 `progressive hydration`：仍然享受 `SSR` 的首屏优势，同时通过拆分与延迟降低 `hydration` 成本。([Patterns][6])

把它落到页面结构上，会长得像这样：

* `Header` 与 `Hero CTA`：优先水合，保证立刻可点
* `Below the fold` 的推荐区：等空闲或滚动到可视区再水合
* `Footer`：甚至可以不水合，保持静态

### 事件回放 `event replay`：用户早点击了也不丢

另一个用户体验坑是：页面内容已经出来，但 `hydration` 尚未完成时用户点击了按钮，这次点击可能被丢掉。Angular 的 `hydration` 指南里专门描述了 `Event Replay`：在 `hydration` 完成前捕获用户交互，待水合结束后再回放，确保交互不会丢失。([Angular][7])

即便你不用 Angular，这个概念依然很值得借鉴：它本质是在解决“接管期的交互一致性”。

---

## 七、以 Next.js 为例：`use client`、组件边界与 `hydration` 的关系

在 Next.js 的 App Router 体系里，组件默认是 Server Component，只有显式标记 `use client` 的组件才会进入客户端包并参与 `hydration`。Next.js 文档把它描述为一种边界声明：`use client` 用来划分 Server 与 Client 模块图，一旦标记，相关依赖与子组件都会进入 client bundle。([Next.js][8])

这意味着一件很重要的事：

* **不是所有服务端渲染出来的 UI 都必须水合**
* 只有需要浏览器能力（事件、状态、`window`、`useEffect`）的部分才需要成为 Client Component

从架构角度看，这让 `hydration` 从“整页动作”变成“局部动作”，你可以更精细地控制 JS 体积与主线程压力。

---

## 八、真实业务场景拆解：`hydration` 的坑通常不是理论问题，而是链路问题

### 场景 1：内容站点 + 评论区

* 文章正文用 `SSR` 输出，确保 `SEO` 与首屏可读
* 评论区用 Client Component，等用户滚动到评论区时再加载与水合
* 点赞按钮在首屏，优先水合，避免用户点击无响应

这类站点最容易踩到的坑是第三方脚本（广告、埋点）阻塞主线程，导致 `hydration` 推迟，用户误以为站点坏了。web.dev 提醒的“看起来交互但实际不能响应输入”在这种站点里非常常见。([web.dev][2])

### 场景 2：电商详情页 + 实时信息

* 商品标题、价格、主图、购买按钮：`SSR` + 优先水合
* 实时库存与倒计时：服务端输出稳定占位，客户端接管后再更新
* 推荐列表与评价瀑布流：延后水合或按需水合

这里最常见的 `hydration mismatch` 源头就是时间与随机性。Next.js 文档提供的 `suppressHydrationWarning` 适合用于那些“差异可接受但结构必须保留”的局部内容。([Next.js][4])

---

## 九、把 `hydration` 做好的实战准则：稳定、可控、可观测

下面这些准则，来自大量团队踩坑后的共识，背后都能对应到上面拆解的某个内部动作。

### 1）保证服务端与客户端首轮渲染的确定性

* 避免在 render 路径里直接用 `Date.now()`、`Math.random()`
* 格式化逻辑保持一致（地区、时区、货币）
* 必须依赖浏览器信息时，用占位 + 客户端副作用更新

这样做的直接收益是减少 `hydration mismatch`，避免框架放弃复用导致更大成本。([Next.js][4])

### 2）把交互边界缩小，别让整页都背 `hydration` 成本

* 在 Next.js 里减少 `use client` 的蔓延范围
* 把纯展示组件留在服务端，交互组件才进客户端

这对应 Next.js 文档强调的模块图边界原则：`use client` 会把依赖树带进 client bundle，边界越大，客户端成本越高。([Next.js][8])

### 3）对 `INP` 敏感的页面考虑渐进式或选择性水合

* 用 `Suspense`、按区块拆分、滚动触发等方式延后不关键区域
* 优先保证首屏关键控件可点

Vercel 在 nextjs.org 的案例说明了这种策略对 `TBT` 的潜在收益。([Vercel][5])
patterns.dev 对渐进式 `hydration` 的总结也在强调“拆分与延迟”是核心。([Patterns][6])

### 4）把接管期的用户交互考虑进去

* 如果页面在可见后很久才可交互，用户会提前点击
* 事件回放思路可以减少挫败感

Angular 文档对 `Event Replay` 的描述提供了一个很清晰的可参考模型：先捕获，再回放。([Angular][7])

---

## 十、用一句话把 `hydration` 讲到位

`hydration` 不是给 `HTML` 贴个 `onClick` 那么简单，它是一套“在不推倒重建的前提下，让框架接管现有 DOM”的系统工程：**客户端需要再渲染一遍组件树来得到期望结构，逐节点对齐并复用服务端 DOM，建立组件与节点的双向关联，接入事件系统与调度器，初始化状态并在合适时机触发副作用**。React 官方对 `hydrateRoot` 的定义把它概括得很精准：把组件逻辑附着到服务端生成的 `HTML` 上，让快照变成可交互应用。([React][1])
而 web.dev 的提醒也同样关键：带 `rehydration` 的 `SSR` 虽然能让内容更早出现，但水合成本可能拖垮交互指标，导致页面“看起来好了却点不动”。([web.dev][2])


[1]: https://react.dev/reference/react-dom/client/hydrateRoot?utm_source=chatgpt.com "hydrateRoot"
[2]: https://web.dev/articles/rendering-on-the-web?utm_source=chatgpt.com "Rendering on the Web | Articles"
[3]: https://www.gatsbyjs.com/docs/conceptual/react-hydration/?utm_source=chatgpt.com "Understanding React Hydration | Gatsby"
[4]: https://nextjs.org/docs/messages/react-hydration-error?utm_source=chatgpt.com "Text content does not match server-rendered HTML"
[5]: https://vercel.com/blog/improving-interaction-to-next-paint-with-react-18-and-suspense?utm_source=chatgpt.com "Improving INP with React 18 and Suspense"
[6]: https://www.patterns.dev/react/progressive-hydration/?utm_source=chatgpt.com "Progressive Hydration"
[7]: https://angular.dev/guide/hydration?utm_source=chatgpt.com "Hydration"
[8]: https://nextjs.org/docs/app/getting-started/server-and-client-components?utm_source=chatgpt.com "Getting Started: Server and Client Components"


在 SSR 体系里，用户拿到的首屏内容往往是一段已经“长得像页面”的 HTML。它能被浏览器立刻解析成 DOM 并绘制到屏幕上，但此时页面依然像一张“干的照片”：看得到，却不一定点得动。hydration 的任务，就是把这张静态快照变成真正能响应交互的应用，把组件逻辑、事件处理、状态管理接回到浏览器端运行。React 文档用非常直白的措辞描述了这件事：hydration 会把组件逻辑“附着”到服务端生成的初始 HTML 上，让它变成可交互的应用。(React)

Web 应用 SSR Hydration 阶段的深入拆解：从一张 HTML 快照到真正可交互应用，中间到底发生了什么

在 SSR 体系里，用户拿到的首屏内容往往是一段已经“长得像页面”的 HTML。它能被浏览器立刻解析成 DOM 并绘制到屏幕上，但此时页面依然像一张“干的照片”：看得到，却不一定点得动。hydration 的任务，就是把这张静态快照变成真正能响应交互的应用，把组件逻辑、事件处理、状态管理接回到浏览器端运行。React 文档用非常直白的措辞描述了这件事：hydration 会把组件逻辑“附着”到服务

紫薇堂堂主

其他

SSR hydration技术将静态HTML转化为可交互应用，通过客户端框架复用服务端渲染的DOM结构，建立事件系统和状态管理。React的hydrateRoot方法实现组件逻辑与现有DOM的对齐，提升首屏渲染速度的同时确保交互性。注意避免hydration mismatch问题，优化INP指标，采用渐进式hydration策略提升用户体验。

数据结构

容器

2026采购季 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

SSR hydration技术将静态HTML转化为可交互应用，通过客户端框架复用服务端渲染的DOM结构，建立事件系统和状态管理。React的hydrateRoot方法实现组件逻辑与现有DOM的对齐，提升首屏渲染速度的同时确保交互性。注意避免hydration mismatch问题，优化INP指标，采用渐进式hydrat...

Web 应用 SSR Hydration 阶段的深入拆解：从一张 HTML 快照到真正可交互应用，中间到底发生了什么-腾讯云开发者社区-腾讯云

Web 应用 SSR Hydration 阶段的深入拆解：从一张 HTML 快照到真正可交互应用，中间到底发生了什么

Web 应用 SSR Hydration 阶段的深入拆解：从一张 HTML 快照到真正可交互应用，中间到底发生了什么

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐