React 组件库的热更新（HMR）协议：源码分析 React Refresh 如何在替换代码时保留 useState 内部内存块

各位好！欢迎来到“React 内部黑魔法”系列讲座的现场。我是你们的主讲人，一个在代码世界里摸爬滚打多年，见过无数 npm install 失败和 TypeError: Cannot read properties of undefined 的资深“代码巫师”。

今天，我们要聊的话题非常硬核，非常“变态”，也非常……有用。

想象一下，你正在开发一个大型 React 应用，你正在疯狂地修改组件逻辑，调优样式，优化性能。突然，你保存了文件。如果你的热更新（HMR）只是简单的“卸载 -> 重新挂载”，那么恭喜你，你刚刚写的那 50 行代码带来的所有状态，瞬间就会灰飞烟灭。你的表单数据清空了，你的计数器归零了，你的滚动位置没了。

这就像是你正在玩《塞尔达传说》，突然游戏提示“文件已损坏，重新开始”，你刚走到魔王城门口……

这种体验简直是噩梦。所以，React 团队为了拯救你的发际线，搞出了一个叫 React Refresh 的东西。

它就像是一个隐形的刺客，潜伏在你的浏览器里。当你的代码发生变化时，它不是把整个组件杀掉，而是悄悄地给组件注入一点“迷魂药”，让 React 以为这个组件还是原来那个组件，只是换了个新皮肤。

那么，它是怎么做到的？它如何在替换代码的同时，保住 useState 里的那一堆内存数据？今天，我们就扒开它的裤腰带（不是真的），看看它的核心原理。

准备好了吗？让我们开始这场关于内存、欺骗和协议的深度探险。

---

第一部分：React 的“谎言”——伪造 React.createElement

React 的核心渲染机制，本质上是在构建一棵树，这棵树叫 Fiber。当你调用 React.createElement(Component, props, children) 时，React 并不知道 Component 是什么，它只知道要去执行这个函数，然后把返回的 JSX 转换成虚拟 DOM。

React Refresh 的第一招，叫做 “狸猫换太子”。

在开发环境下，react-refresh/runtime 会劫持全局的 React 对象。它做了一个极其大胆的事情：伪造了 React.createElement 函数。

请看下面这段极其精简的伪代码（为了理解，我简化了很多细节）：

// react-refresh/runtime 内部的大致逻辑（极度简化版）

const oldCreateElement = React.createElement;

React.createElement = function(type, config, children) {
  // 1. 检查这个 type 是不是我们关注的组件
  // React Refresh 会给所有函数组件打上标记
  if (isLikelyComponentType(type)) {
    // 2. 关键点来了：伪造一个 ReactElement 对象
    // React 在内部判断组件是否更新、是否复用，主要看这个 type 对象
    // 我们给这个 type 加上特殊属性，骗过 React
    return {
      $$typeof: Symbol.for('react.element'),
      type: type, // 这里是组件函数本身
      key: null,
      ref: null,
      props: config,
      // ... 其他标准属性
      __reactFiber$: null // Fiber 树的引用
    };
  }

  // 如果不是组件（比如原生 div），就交给原来的 createElement 处理
  return oldCreateElement.apply(this, arguments);
};

这听起来很疯狂，对吧？你只是改了组件的内部逻辑，但 React.createElement 却被替换了。这样做有什么用？

作用一：欺骗 React 的 Fiber 复用机制。

当你的代码更新，Webpack 检测到变化，重新加载了你的模块。此时，浏览器内存里有两个 Counter 函数。一个旧的，一个新的。

• 没有 React Refresh 时： React 看到新的 Counter，觉得这是一个新东西，于是调用 React.createElement。React.createElement（旧版）返回一个新的对象。React 拿着这个新对象去和旧的 Fiber 节点比对。发现类型变了（旧的是函数 A，新的是函数 B），于是决定：卸载旧的，挂载新的。状态丢失！
• 有 React Refresh 时： React 看到新的 Counter，调用伪造的 React.createElement。这个伪造函数返回的对象里，type 依然是 Counter 函数。React 拿着这个对象去和旧的 Fiber 节点比对。发现类型没变（都是 Counter）。于是决定：复用旧的 Fiber 节点。状态保留！

这就像是你把书的第 50 页撕下来换成了新的一页，但书的封面和书脊没变，图书馆以为书还是那本，只是内容更新了。

---

第二部分：组件的“身份证”——isReactComponent 与 displayName

但是，光有 type 还不够。React 还有一个检查机制，它会看这个 type 到底是不是一个“React 组件”。

在 React 的旧版本中，它通过检查 type.isReactComponent 这个属性来判断。如果一个对象有这个属性，它就是一个类组件（Class Component）。

React Refresh 也很机智，它把这个属性也加上了：

// React Refresh 偷偷给组件函数加属性
function Component(type) {
  // ... 省略一堆检查代码

  // 这是一个标记，告诉 React："嘿，我是 React 组件，别把我当普通函数处理"
  type.isReactComponent = true;

  // 还有一个更重要的标记：displayName
  // 这个名字通常和组件变量名一致，比如 Counter
  type.displayName = "Counter"; 

  return type;
}

为什么 displayName 这么重要？

因为有时候，代码更新后，函数的引用地址变了（比如 Webpack 重新生成了哈希值），但函数名没变。React Refresh 通过 displayName 来确认：“虽然这个函数地址变了，但它还是那个 Counter，可以保留状态。”

这就好比，虽然你的身份证号变了，但你的名字没变，警察叔叔（React）通过名字认出你还是那个人。

---

第三部分：协议的传递——__REACT_DEVTOOLS_GLOBAL_HOOK__

光在浏览器里“欺骗” React 还不够，React Refresh 还需要告诉服务器：“嘿，兄弟，我这边代码变了，你快把新代码发过来，但我这边有些状态还没死，你帮我处理一下。”

这中间需要一个协议。这个协议不是写在浏览器里的，而是写在 Webpack 或 Vite 这种构建工具里的。

React Refresh 利用了 React DevTools 的一个全局钩子：__REACT_DEVTOOLS_GLOBAL_HOOK__。

在开发环境下，Webpack 会配置一个插件，它会拦截文件的保存事件。当文件变化时，Webpack 会调用 React Refresh 的协议。

这个协议长这样（简化版）：

// webpack-dev-server 发送给 React Refresh 的消息
const payload = {
  type: 'react-refresh',
  // 这里的 componentId 是 React Refresh 给每个组件分配的唯一 ID
  // 它是根据组件的 displayName 和文件路径生成的
  componentId: 'Counter-component-id-12345', 

  // action 决定了怎么更新
  action: 'replace',

  // metadata 包含了组件的元数据，比如它的依赖关系
  // React Refresh 需要知道这个组件依赖了哪些其他组件，才能决定是否需要更新它们
  metadata: {
    name: 'Counter',
    // ... 其他元数据
  }
};

// React Refresh 的 runtime 接收到这个消息
window.__REACT_DEVTOOLS_GLOBAL_HOOK__.send(payload);

这个协议的核心在于 componentId。

React Refresh 会为每个组件函数维护一个映射表：ComponentId -> ComponentFunction。

当你保存文件时：

1. Webpack 检测到 Counter.js 变了。
2. Webpack 找到 Counter.js 对应的 componentId。
3. Webpack 发送消息：componentId: 'Counter-123', action: 'replace'。
4. React Refresh Runtime 接收到消息，找到对应的组件函数，把它替换成新代码。
5. 最关键的一步：Runtime 会告诉 React：“嘿，这个 Counter 函数现在指向了新代码，但它是同一个 componentId，所以请复用旧的 Fiber 节点！”

---

第四部分：灵魂的延续——useState 内部状态如何保留

现在，让我们深入到最核心的部分：useState。

当你调用 useState(0) 时，React 做了什么？它会在当前的 Fiber 节点上创建一个状态节点。

// React 内部处理 useState 的伪代码
function useState(initialValue) {
  // 1. 获取当前正在渲染的 Fiber 节点
  const fiber = currentlyRenderingFiber;

  // 2. 检查这个节点是否已经有 memoizedState（即是否已经初始化过）
  if (fiber.memoizedState === null) {
    // 第一次渲染，创建新的状态节点
    fiber.memoizedState = {
      value: initialValue,
      queue: {
        pending: null,
        dispatch: dispatchAction
      }
    };
  } else {
    // 已经初始化过，直接返回旧的状态
    // React Refresh 的魔法就在这里体现！
    // 因为 React Refresh 复用了旧的 Fiber 节点，
    // 所以这里的 fiber.memoizedState 指向的，依然是旧的状态对象！
    return fiber.memoizedState.value;
  }
}

场景还原：

假设你有一个 Counter 组件：

function Counter() {
  const [count, setCount] = useState(0); // 初始化状态为 0

  console.log('当前计数:', count);

  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

步骤 1：初次加载。

• React 创建 Fiber 节点，memoizedState 指向 {value: 0, ...}。
• 返回 0，渲染按钮显示 0。

步骤 2：用户点击，状态变为 1。

• setCount 被调用，更新 memoizedState.value 为 1。
• 重新渲染，返回 1。

步骤 3：代码热更新（HMR）——关键时刻。

• 你修改了 Counter 函数的内部逻辑，比如把 console.log 改成了 console.warn。
• React Refresh 发动攻击：
  1. 它劫持了 React.createElement，确保 React 复用旧的 Fiber 节点。
  2. 它通过协议通知服务器，把 Counter 函数替换成新代码。
• 组件重新执行：
  • 函数体执行了（你的新代码）。
  • useState 再次被调用。
  • 因为 Fiber 节点没变，fiber.memoizedState 还是指向那个旧对象 {value: 1, ...}。
  • useState 返回 fiber.memoizedState.value，也就是 1。
• 结果：按钮显示 1。你的状态保住了！

这就像是你给一本书换了内容，但书签还停留在第 10 页，而不是从第一页开始读。

---

第五部分：副作用与边界情况——为什么有时候 useEffect 不会跑？

既然 React Refresh 这么强，那为什么有时候你会看到警告？为什么有时候 useEffect 没有触发？

这里涉及到了 React 的 Effect 阶段。

useEffect 是在渲染完成之后执行的。React Refresh 虽然保住了状态，但它需要决定是否要重新运行 useEffect。

React Refresh 使用了一个非常聪明的策略：签名检查。

它会给组件生成一个“签名”，这个签名基于组件的依赖项。

// React Refresh 生成签名的逻辑
function getSignature(type, componentId) {
  // 1. 获取组件的 displayName
  const name = type.displayName;

  // 2. 获取组件依赖的其他模块（比如 import 的组件）
  const dependencies = getDependencies(type);

  // 3. 生成一个哈希值
  return hash(name, dependencies);
}

场景还原：

你的 Counter 组件依赖了一个 Button 组件。

import { Button } from './Button';

function Counter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    console.log('Count changed');
  }, [count]); // 依赖 count
}

情况 A：只改了 Counter 的内部逻辑（没改依赖）。

• Webpack 发送消息，componentId 对应的函数被替换。
• React Refresh 检查签名：签名没变（名字没变，依赖的 Button 没变）。
• 结果：React 认为“这个组件没变”，所以连 useEffect 都不跑（因为 React 优化了，觉得没必要）。状态保留，副作用不触发。

情况 B：你改了 Button 组件。

• Button 的 displayName 变了，或者它的代码变了。
• React Refresh 检查签名：签名变了！
• 结果：React Refresh 发现组件变了，它必须告诉 React：“兄弟，这个组件变了，虽然 Fiber 节点我帮你留着了，但副作用你得重新跑一遍！”
• 此时，useEffect 会重新运行。

情况 C：你重命名了文件。

• 如果你的组件名变了，或者文件路径变了，displayName 可能会变。
• React Refresh 会检测到这一点，然后放弃，直接卸载并重新挂载组件。它会抛出一个警告：“组件签名已更改，无法热更新。正在重新加载。”

---

第六部分：深入代码注入——React Refresh Runtime 的真实面目

为了让上述机制工作，React Refresh Runtime 必须在模块加载时注入代码。这段代码非常长，非常复杂，充满了各种边界情况的处理。

我们来看看 Runtime 做了哪些事情：

1. 劫持模块系统：
   它会监听 import.meta.hot（Vite）或 module.hot（Webpack）。

2. 注册组件：
   当一个模块加载完成，Runtime 会扫描这个模块里的所有函数，判断它们是不是组件（通过检查 isLikelyComponentType）。如果是，就调用 register(type, id)。

   function register(type, id) {
     // 将组件函数和 componentId 存入一个全局 Map
     componentMap.set(id, type);
   
     // 给组件函数打上特殊标记
     type[ReactRefreshConsts.REACT_REFRESH_TYPE] = 'function';
   }

3. 监听更新：
   当 module.hot.accept 触发时，Runtime 会找到对应的组件 ID，替换函数引用，然后触发重新渲染。

---

第七部分：常见坑与排雷指南

作为资深专家，我必须告诉你们，这个黑魔法虽然强大，但它也有“发疯”的时候。

1. 重构导致的“热更新失败”
如果你把一个组件拆分成两个，或者把两个组件合并成一个。

• React Refresh 会发现 displayName 不匹配，或者组件 ID 对不上。
• 现象：页面白屏，或者状态丢失。
• 解法：重启开发服务器。

2. useRef 和 useMemo 的陷阱
React Refresh 主要是为了保留 useState 的状态。对于 useRef 和 useMemo，它也做了处理，但比较微妙。

• useRef：React Refresh 会尝试保留 ref.current 的值。但如果 ref 指向的是外部对象，而那个外部对象的引用变了，React Refresh 就会失效。
• useMemo：如果依赖项变了，React Refresh 通常会触发重新计算。但如果依赖项没变，它会保留旧值。

3. Class Component 的悲剧
React Refresh 对 Class Component 的支持非常有限。

• this.state 无法保留。
• this.props 可能会丢失。
• 原因：Class Component 的实例化机制和函数组件完全不同，React Refresh 很难在 Class Component 上做“灵魂附体”。

4. 非标准组件（如 react-three-fiber）
如果你的组件库不是标准的 React 组件，React Refresh 可能会失效。因为它无法识别 isLikelyComponentType。

---

第八部分：总结——这不是魔法，是工程

好了，各位同学，我们今天的讲座接近尾声。

让我们回顾一下 React Refresh 的核心原理：

1. 伪造者：它伪造了 React.createElement，让 React 以为组件函数没变。
2. 间谍：它通过 __REACT_DEVTOOLS_GLOBAL_HOOK__ 与 Webpack/Vite 通信，知道代码什么时候变了。
3. 身份证：它通过 displayName 和 isReactComponent 标记，让 React 能够识别组件的身份。
4. 记忆者：它通过复用 Fiber 节点的 memoizedState，让 useState 能够从旧的状态中读取数据。

React Refresh 的本质，就是在运行时动态地修改了 React 的渲染逻辑。它牺牲了一点点性能（每次渲染都要检查标记），换取了巨大的开发体验提升。

它就像是给 React 的渲染引擎植入了一个“补丁程序”。当你的代码发生变化时，这个补丁程序会拦截请求，把旧的 Fiber 节点“复活”，让新的代码逻辑在旧的躯壳上运行。

所以，当你下次在浏览器里看到代码更新后，表单数据还在，计数器还在跳动，而你的手指甚至不需要离开键盘时，请记住：这背后不是什么神仙显灵，而是 React Refresh 在默默地在内存里帮你“续命”。

不要滥用它（比如不要在热更新期间疯狂点击按钮导致内存泄漏），但一定要感谢它，感谢 React 团队让我们告别了那个“每次保存都要刷新整个页面”的黑暗时代。

今天的讲座就到这里，我是你们的资深编程专家。如果你们在热更新中遇到奇怪的问题，记得检查你的 displayName，检查你的 import 依赖，或者直接重启服务器。祝大家编码愉快，Bug 少少，热更新丝滑！