剧透预警：当 React 发现剧本穿帮了 —— 水合 mismatches 的源码探案录

各位未来的 React 架构师，各位正在为“hydration mismatch”而掉头发的工程师们，大家好！

今天我们不聊怎么把 useState 写得更花哨，也不聊怎么优化 useMemo 的内存占用。今天我们要聊的是 React 最“神经质”、最“多疑”的时刻——水合（Hydration）。

想象一下，你在写剧本。服务端是那个“剧透狂魔”，它在剧本的第一页就写死了：“主角手里拿着一杯热可可，杯口冒着白烟。” 然后你把这个剧本发给观众看。观众（浏览器）看着剧本，心想：“嗯，这看起来很正常。”

但是，当你切换到客户端，真正开始写代码渲染时，你手一抖，写成了：“主角手里拿着一杯冰美式。” 然后你把这段代码发给浏览器运行。

这时候，React 就会跳出来尖叫：“喂！剧本不对啊！第一页明明说是热可可，你这儿怎么是冰美式？”

这就叫“水合不一致”。今天，我们就把 React 的裤子扒下来（当然是代码层面），看看它是怎么在代码深处偷偷比对服务端和客户端的数据，又是如何在发现“穿帮”时进行容错和抢救的。

---

第一章：潜伏在 DOM 里的“双胞胎”

要理解水合比对，首先得理解 React 在客户端渲染时做了什么。

当你在浏览器里使用 createRoot 时，React 会创建一个 Fiber 树。Fiber 是 React 的新架构，它是 React 节点的虚拟化身。

当你在服务端渲染（SSR）时，React 输出的是 HTML 字符串。这些 HTML 字符串被浏览器解析成了真实的 DOM 节点（比如 <div>, <span>）。

问题来了：怎么让 Fiber 树和 DOM 树对上号？

React 的策略非常简单粗暴：“照葫芦画瓢”。它在客户端创建 Fiber 节点的同时，会去寻找对应的 DOM 节点，然后建立联系。

这个联系叫什么？叫 hydrationState。这就像是一个秘密接头暗号。

// 伪代码示意：React 在创建 Fiber 节点时
const fiber = {
  stateNode: domNode, // 这个 Fiber 节点挂载在哪个 DOM 上
  hydrationState: {
    isHydrating: true, // 此时是水合模式
    // ... 更多状态
  }
};

所以，当 React 开始执行水合逻辑时，它手里拿着服务端的剧本（DOM），面前摆着客户端的新剧本（Fiber），开始了逐行比对。这就好比一个严苛的监考官。

---

第二章：比对现场 —— hydrateNode 的抓捕行动

核心比对逻辑主要发生在 react-reconciler 包里的 hydrateNode 函数。我们要深入这个函数，看看它是怎么“抓现行”的。

1. 类型匹配：名字没对上？

首先，React 会检查 DOM 节点的类型和服务端生成的 Fiber 类型是否一致。

// 源码逻辑极简版
function hydrateNode(
  fiber,
  domNode,
  parentContext,
  isSuspenseBoundary
) {
  // 获取 DOM 的真实类型，比如 'div', 'h1', 'span'
  const domType = domNode.nodeType;

  // 获取 Fiber 的类型
  const fiberType = fiber.type;

  // 这里的检查非常细致
  // 注意：HTML 标签名转小写，组件名保持原样
  if (domType !== fiberType) {
    // 如果类型对不上，这就是第一重“穿帮”。
    // React 会怎么做？它会把这个 DOM 节点从 hydrating 状态中踢出去，
    // 回归普通的客户端渲染模式。
    resetHydrationState(); 
    // 然后继续执行下面的 mount logic，重新创建 DOM。
  }

  // ... 处理 Props
}

幽默时刻： 如果服务端输出了 <DIV>（大写），而客户端生成的 Fiber 期望的是 <div>（小写），React 会觉得很羞愧。它会想：“服务端居然用大写？这是什么复古字体？不管了，咱们重新挂载吧。”

2. Props 对比：属性不对劲？

如果标签名对上了，接下来就是检查属性。这是最容易出问题的地方。

服务端渲染：

<div class="container" width="100%">
  Hello
</div>

客户端 Fiber：

// React 客户端可能会生成
<div className="container" style={{ width: '100%' }}>
  Hello
</div>

当 React 检查到 width="100%" 时，发现 Fiber 里没有 width 属性，或者 Fiber 里的 className 对应的 DOM 属性是 class 而不是 className，它就会判定为 Mismatch。

容错机制一：dangerouslySetInnerHTML 的坑

这是最常见的 Mismatch 来源。React 对 children 的处理非常严格。如果是 HTML 标签，它会比对 HTML 字符串；如果是组件，它会比对 Fiber。

但是，如果你用了 dangerouslySetInnerHTML={{ __html: '<b>Bold</b>' }}，React 会傻眼。因为服务端直接输出了 <b>Bold</b>，而客户端 Fiber 却把它当成了一个 TextNode。

// 源码逻辑：React 检查 children
if (fiber.type === 'HTML' && domNode.textContent !== fiber.memoizedProps.dangerouslySetInnerHTML.__html) {
  // “喂！服务端说文本是 'Hello'，客户端 Fiber 说文本是 'Hello<b>Bold</b>'？你耍我呢？”
  throw new Error('Hydration failed');
}

3. 文本节点比对：最细碎的纠察

React 遍历 DOM 树的子节点，也遍历 Fiber 树的 child 链表。如果发现一个 DOM 节点是文本节点（textNode），而对应的 Fiber 节点也是个文本节点，React 会比对 textContent。

const domText = domNode.textContent;
const fiberText = fiber.memoizedProps.children;

if (domText !== fiberText) {
  // Mismatch Alert!
  console.warn(
    'Text content does not match server-rendered HTML.n' +
    'Server: "%s"n' +
    'Client: "%s"',
    domText,
    fiberText
  );
}

如果比对失败，React 怎么办？它不能把用户面前的 DOM 删了重写，那样会导致闪烁。它必须利用 Fiber 的特性进行“修复”。

---

第三章：报错后的“紧急避险”逻辑

这是本文最核心的部分：当 React 发现剧本穿帮了，它怎么救场？

React 有一套非常复杂的“紧急避险”机制。当比对失败时，React 不会直接崩溃，而是会尝试各种手段来恢复“假象”。

状态一：首次穿帮

假设服务端写了 <div>1</div>，客户端写了 <div>2</div>。

1. 检测：hydrateNode 发现文本不匹配。
2. 决策：React 会标记当前节点为 didSuspend（假设它能检测到这是首次错误）。
3. 执行：React 会尝试执行 revertHydrationState()。

revertHydrationState 做了什么？

它会把当前节点的 stateNode（DOM）从 hydration 状态中移除，并把它标记为 待删除（deletion）。同时，它会把这个 DOM 节点挂载到 Fiber 树的父节点的 deletions 列表中。

// 源码逻辑：revertHydrationState 的核心思想
function revertHydrationState() {
  // 遍历所有 fiber
  // ...
  // 如果这个 fiber 是在 hydration 阶段匹配上的，现在发现错了
  if (fiber.stateNode) {
    // 把 DOM 节点放回“待删除队列”
    parentFiber.deletions.push(fiber.stateNode);
    // 清空当前的 hydration 状态
    fiber.stateNode = null;
    fiber.hydrationState = null;
  }
}

结果：React 会把这棵树标记为“损坏”。在接下来的 Commit 阶段，React 会执行删除操作。删除完之后，它就退出了 hydration 模式，重新进入 mount 模式，重新创建 DOM 节点。

用户体验：用户会看到一瞬间的内容跳动（从 1 变成 2，或者先显示 1，然后 1 消失，2 出现）。

状态二：多次穿帮 —— 放弃治疗

有时候，剧本不仅仅是写错了一次，而是服务端和客户端渲染逻辑本身就存在结构性差异（比如服务端用 map，客户端用 if-else）。

React 有一个计数器，叫做 errorRetryThreshold。默认情况下，这个值是 3。

如果你在前三次尝试修复都失败了，React 会判定这个页面“无可救药”，直接放弃水合。

if (isHydrating && didSuspend && fiber.hydrationState && isRetryable) {
  // 检查重试次数
  if (retryCount >= errorRetryThreshold) {
    // 停止水合！
    resetHydrationState();
    // 完全抛弃 DOM，开始从零挂载
    // 此时，Fiber 树接管一切，DOM 树彻底沦为废弃垃圾
    return;
  }
}

幽默时刻：这就像一个严厉的家长。孩子第一次考试考砸了，家长想：“哎呀，可能只是粗心，下次注意。” 第二次考砸了，家长说：“可能心态不好。” 第三次考砸了，家长说：“行了行了，别费劲了，你自己学吧（直接挂载）。” 第四次再错，家长就把作业本撕了：“重写！”

---

第四章：那些“被原谅”的错误 —— 容错与策略

React 并不是个死脑筋的机器。为了用户体验，它设定了很多“豁免权”。

1. Suspense 的保命符

这是 React 18 最伟大的特性之一。如果服务端没有 <Suspense>，而客户端有，或者反之。

React 的水合逻辑会检测到这种情况。如果客户端处于 loading 状态（比如数据还没回来），React 会认为：“哦，这是异步数据加载导致的差异。” 它会保留服务端的 HTML，直到客户端的数据加载完成，然后再进行替换。

这就像：服务端给了一张黑底白字的草图，客户端数据还没回来时，先让观众看这张草图；等数据回来了，再把草图擦掉，画出一张高清大图。用户根本感觉不到中间发生了什么。

2. disableHydrationWarning 的黑科技

在 React 18 之前，如果你在水合阶段遇到一些非关键性的差异，比如事件监听器的差异（服务端没有事件监听器，客户端有），React 会疯狂报 Warning。

React 18 引入了 disableHydrationWarning，允许你在特定节点上关闭警告。这在处理复杂的第三方库时非常有用。

// 源码逻辑：设置 disableHydrationWarning
function hydrateNode(fiber, domNode, parentContext, isSuspenseBoundary) {
  // ...
  if (fiber.memoizedProps.dangerouslySetInnerHTML) {
    // 如果是 dangerouslySetInnerHTML，不检查文本内容差异，防止误报
  }
  // ...
}

3. 回调函数 —— 难以水合的痛点

这是 React 水合的大杀器。假设服务端渲染了：
<button onclick="handleSubmit()">提交</button>

客户端 Fiber 渲染为：

<button onClick={handleSubmit}>提交</button>

检测：React 比对 props 时发现，服务端的 onclick 属性是一个字符串，而客户端的 onClick 是一个函数。

后果：React 会立刻抛出 Error，因为函数引用在水合时是不稳定的。

容错：React 会把这段区域标记为需要卸载。如果你使用了 enableLegacyFiberFeatures（或者某些特定配置），React 可能会保留这个 DOM 节点，但会忽略事件属性。

但在现代 React 中，遇到这种情况，React 会直接放弃 hydration，转而挂载。

---

第五章：源码里的“侦探工具”

如果你真的想在源码里找到这些逻辑，应该看哪里？

1. 入口：react-dom 的 hydrateRoot。
2. 核心：react-reconciler 中的 hydrateImpl。
3. 比对：hydrateNode 函数。
4. 重置：resetHydrationState 函数。
5. 标记：didSuspend 标志位。

让我们看一段更具实战意义的源码解析，模拟 hydrateNode 中处理 shouldHydrate 的逻辑：

function shouldHydrate(
  fiber,
  node
) {
  // 如果 fiber 是个文本节点
  if (fiber.type === REACT_TEXT_TYPE) {
    // 如果 DOM 也是文本节点，那可以继续水合比对
    if (node.nodeType === 3) {
      return true;
    }
    return false;
  }

  // 如果 fiber 是个组件
  if (fiber.type !== null && typeof fiber.type === 'function') {
    // 检查 DOM 节点类型是否匹配
    // 注意：这里涉及到 nodeType 的转换
    if (node.nodeType === 1) {
      return true;
    }
    return false;
  }

  // 其他情况（比如 fragment 等）
  return false;
}

// 在 hydrateNode 内部：
function hydrateNode(...args) {
  const domNode = args[1];
  const fiber = args[0];

  if (!shouldHydrate(fiber, domNode)) {
    // 如果连该不该水合都判断错了，那肯定要报错
    // 甚至要处理 deletion（比如服务端有，客户端没）
  }

  // ... 继续比对 props
}

处理删除节点的逻辑（Deletion）

这是最令人头秃的部分。服务端有 <div>1</div><div>2</div>，客户端因为逻辑变更，变成了 <div>1</div>。那个 <div>2</div> 怎么办？

React 的 Fiber 树在客户端构建时，会从 rootFiber 开始遍历。
如果服务端 DOM 有两个子节点，客户端 Fiber 树遍历完一个后，发现服务端还有个节点没看。

React 会把这个“没看过的 DOM 节点”标记为 deletion，并在 Commit 阶段执行删除。

// 源码逻辑：hydrateTreeFromHostContainer
// 当 Fiber 遍历完，发现 DOM 树还有残留
if (domNode.nextSibling) {
  // 将剩余的 DOM 节点全部挂载到 fiber.deletions
  let nextSibling = domNode.nextSibling;
  while (nextSibling) {
    fiber.deletions.push(nextSibling);
    nextSibling = nextSibling.nextSibling;
  }
}

这就像你在把衣柜里的衣服归类。服务端给你一堆衣服（DOM），你一件件拿出来（Fiber）。你挑完了，发现衣柜里还剩两件你根本没看过的。React 会想：“这肯定是以前留下的，给扔了吧。”

---

第六章：调试指南 —— 如何像 React 一样思考

作为一个资深工程师，当你看到控制台出现那行著名的警告时，不要慌，不要怒，要像 React 一样思考。

错误示例 1：CSS 样式导致的差异

• 现象：服务端 width: 100px，客户端 width: 100%。
• React 视角：文本内容一致，但 DOM 属性不一致。
• 原因：CSS 缓存问题、或者 px 单位和 % 单位在浏览器解析时的表现差异。

错误示例 2：undefined vs null

• 现象：服务端输出 null，客户端输出 undefined。
• React 视角：虽然两者看起来一样，但一个是对象，一个不是。
• 修复：确保代码逻辑对 null 和 undefined 的处理是一致的。

错误示例 3：nextElement 逻辑

• 现象：服务端在列表最后插了个空行，客户端没插。
• React 视角：Fiber 结构差异。

如何利用 disableHydrationWarning？

有时候我们写的是第三方组件，我们没法控制服务端的渲染结果，但客户端渲染是对的。我们可以通过 Context 或者特定逻辑来禁用警告。

// 这是一个极其危险的操作，通常用于调试
function createRoot(container, options) {
  if (options && options.hydrate) {
    // 在某些极端情况下，你可以 hack 进去
    // 但在生产环境中，请避免这样做！
  }
}

---

第七章：恢复 —— 从 Broken 到 Fixed

最后，让我们看看当 Mismatch 发生后，React 是如何把局面“挽救”回来的。

场景：用户访问了你的 SSR 页面。服务端 HTML 是 <h1>Old</h1>。客户端 Fiber 是 <h1>New</h1>。

1. 检测到 Mismatch：hydrateNode 抛出异常，或者 didSuspend 变为 true。
2. 进入 Recovery Mode：
   • resetHydrationState() 被调用。
   • 所有被标记为 isHydrating 的 Fiber 节点被移除。
   • 它们的 DOM 节点被放入 deletions 队列。
3. Commit 阶段：
   • React 执行删除操作，移除 <h1>Old</h1>。
   • React 执行挂载操作，创建 <h1>New</h1>。
4. 恢复正常的 Fiber 流程：
   • 页面内容更新为 New。
   • 状态回到 isHydrating = false。
   • 用户看到的就是最终的正确状态。

代价：
这个过程中，React 会重新解析 DOM 树，重新创建 Fiber 节点。这意味着：

1. 时间开销：第一次渲染会比纯客户端渲染慢一点（因为要解析已有的 HTML）。
2. 内存开销：需要同时持有 DOM 树和 Fiber 树的引用。
3. 闪烁风险：虽然 React 试图避免，但在极端情况下，用户还是可能看到旧内容闪现一下。

---

结语：信任的崩塌与重建

React 的水合机制，本质上是在服务端生成的“假象”和客户端生成的“现实”之间建立信任的过程。

每一次比对都是一次审讯，每一次不一致都是一次背叛。

通过源码我们可以看到，React 并不是冷冰冰的机器。它有容错机制（Suspense），有放弃策略（errorRetryThreshold），有恢复逻辑（resetHydrationState）。它的目标不是百分之百的完美匹配，而是在“完美匹配的成本”和“用户体验”之间找到那个微妙的平衡点。

作为开发者，理解这一机制，能帮你在遇到 SSR 错误时，少写几行 console.log，多写几个 Suspense。

下次当你看到控制台里那行红色的 Hydration failed 时，请深吸一口气，告诉自己：“别怕，React 只是发现剧本穿帮了，它正在努力把它们修改成同一个版本。”

祝大家的水合之路，一路顺风，不报错！