编辑一个计数器组件，把按钮文案从“加一”改成“增加”，浏览器没有整页刷新，计数还在。这就是模块热替换（HMR）在 React 项目里的典型体验。它不像传统 live reload 那样重新加载整个页面，而是只替换发生变化的模块，并尽可能维持组件内部已有的 state、ref 和 effect 状态。理解这背后的机制，能帮你避开那些让状态莫名其妙丢失的坑。

状态保留的实现基础：模块依赖图与 Fast Refresh 签名

传统 HMR 在 Webpack 等打包器里通过模块依赖图工作。文件保存后，打包器找到该模块及其依赖方，通过 module.hot.accept 或 module.hot.dispose 这些 API 把新模块内容推送到浏览器。单靠这些 API 并不能让 React 组件自动更新，因为 React 拥有自己的组件树和 Fiber 节点，如果直接替换模块导出但不触发 React 内部协调，UI 不会变化，更谈不上保留状态。

React Fast Refresh 补上了这一层。它由 Babel 插件 react-refresh/babel 和运行时 react-refresh/runtime 配合完成。编译时，插件会在每个组件文件的导出位置注入注册信息，并给组件函数添加一段隐藏的签名。签名内容主要包括组件名称、Hook 调用顺序以及是否使用了 memo、forwardRef 等包裹。运行时拿到新模块后，先比对旧组件和新组件的签名。如果一致，就调用 React 内部更新方法，把组件定义替换成新函数，但旧 Fiber 节点和 hooks 链表保持不变；如果不一致，则触发一次强制重新挂载。

// 计数器组件：修改按钮文案不会丢失 count
import { useState } from 'react';
export default function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <p>当前计数：{count}</p>
      <button onClick={() => setCount(count + 1)}>增加</button>
    </div>
  );
}

上面的组件在保存后，如果只把按钮文案从“增加”改成“加一”，Fast Refresh 会保留 count 的值。因为组件签名没有变化，useState 的位置和调用顺序完全一致，React 只需替换函数引用，不会卸载 DOM 节点。这里的关键不是 HMR 本身多聪明，而是 React 的 Fiber 架构允许在运行时更换组件定义，同时复用已有的状态存储。

哪些修改可以保留状态，哪些会触发完全刷新

状态保留的最核心规则是：组件类型和 Hook 调用顺序不能改变。只要这条满足，改动通常只影响组件函数内部逻辑，Fast Refresh 就会原地更新。例如修改 JSX 结构、调整事件处理函数、改变 useEffect 内部实现、修改组件内联样式等，都属于安全区。甚至可以在 useEffect 中新增或删除依赖项，只要 Hook 的调用位置和数量不变，状态仍会保留。

反过来，下面这些操作会导致状态丢失。第一，把 useState、useEffect 等 Hook 放在条件语句、循环或提前 return 后面，改变了 Hook 的调用顺序。第二，更改组件的导出方式，比如从命名导出改成默认导出，或者引入新的 HOC 包裹导致签名变化。第三，在组件文件顶部导出的非组件变量被修改，因为 Fast Refresh 会把这种修改视为模块级更新，可能触发依赖该模块的组件整树刷新。第四，修改自定义 Hook 内部的 Hook 顺序，虽然自定义 Hook 本身不是组件，但它的调用会反映到外层组件的签名中。

// 错误示例：将 Hook 放在条件语句中
import { useState } from 'react';
export default function Profile({ isLoggedIn }) {
  if (isLoggedIn) {
    // 破坏了 Hook 顺序，刷新时无法保留状态
    const [name, setName] = useState('');
  }
  const [age, setAge] = useState(0);
  return <div>{isLoggedIn ? name : '游客'}，年龄 {age}</div>;
}

这个例子虽然能通过 React 的开发环境警告，但完全违背了 Hook 规则，Fast Refresh 无法追踪不稳定的签名，最终只能卸载组件重置状态。即便在普通开发中不刷新，这种写法也会导致组件状态错乱。所以保持 Hook 在函数顶层调用，是状态保留实现的前提。

还可以用表格来总结常见改动与状态保留的关系。

从表里可以看出，状态保留的边界并不总是与直觉一致。很多开发者以为只有修改组件本身才会影响状态，但组件文件里混合导出的工具函数同样会触发较粗粒度的刷新，因此工程组织上需要格外注意。

容易踩中的状态丢失陷阱与拆分策略

第一个常见陷阱是匿名默认导出。虽然 Fast Refresh 尽量从变量名推断组件名，但匿名函数的签名稳定性较差，尤其在压缩、包装后可能出现识别失败。更稳妥的做法是始终使用命名函数或命名导出，例如 export default function Counter() 或 export function Counter()。一些旧项目里大量使用 export default () => {...}，在 HMR 下可能每次保存都变成完全刷新。

第二个陷阱是把自定义 Hook、纯函数、常量、类型定义全部堆在组件文件里。组件文件一旦被修改，模块系统会重新执行整个文件，如果文件中包含非组件导出，Fast Refresh 无法只替换组件函数，而是会通知所有导入该文件的模块更新，状态丢失范围被放大。正确做法是把纯工具函数、API 请求封装、常量配置拆到独立模块，组件文件只导出组件和相关联的辅助组件。

// 不推荐：组件与工具函数混合
export const formatPrice = (value) => `¥${value.toFixed(2)}`;
export default function Price({ amount }) {
  return <span>{formatPrice(amount)}</span>;
}
// 推荐：拆分为两个文件
// utils/price.js
export const formatPrice = (value) => `¥${value.toFixed(2)}`;
// components/Price.jsx
import { formatPrice } from '../utils/price';
export default function Price({ amount }) {
  return <span>{formatPrice(amount)}</span>;
}

第三个陷阱发生在高阶组件和装饰器场景。虽然 React.memo、forwardRef 等官方 API 经过特殊处理能被 Fast Refresh 识别，但如果自己封装 HOC 或者在渲染过程中动态创建组件类型，签名判断很可能失效。例如在父组件内部定义子组件，每次渲染都会生成新的组件类型，Hook 状态自然无法对应。这类模式即使不做 HMR 也可能引发挂载性能问题，应当避免。

还有一个隐蔽问题是编辑器自动修复导入顺序或格式化代码。大规模格式化如果改变了文件中多个 Hook 的书写顺序，虽然逻辑上看似等价，但 Fast Refresh 会判定签名变化，导致状态丢失。这不是 BUG，而是签名机制为了保证状态一致性所做的保守处理。

从配置到调试：让状态保留在团队中稳定生效

要让状态保留能力稳定工作，配置上需要把 HMR 与浏览器自动刷新分开。Webpack 项目在 webpack.config.js 中启用 devServer.hot 后，还要确保没有配置 liveReload: true 与 HMR 同时作用。推荐使用 hot: true、liveReload: false 的组合，并引入 ReactRefreshWebpackPlugin。Babel 配置中加载 react-refresh/babel 插件，且该插件只在开发环境启用，生产构建时不要加载，避免注入多余运行时代码。

// webpack.config.js 开发环境关键配置
const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
module.exports = {
  mode: 'development',
  devServer: {
    hot: true,
    liveReload: false,
    historyApiFallback: true,
  },
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            plugins: ['react-refresh/babel'],
          },
        },
      },
    ],
  },
  plugins: [new ReactRefreshWebpackPlugin()],
};

Vite 项目通常不需要手动配置，因为 @vitejs/plugin-react 已经内置了 Fast Refresh 支持，只要在 vite.config.js 中引入插件即可。如果发现修改组件时页面总是整体刷新，可以先检查是否错误地修改了非组件导出，或者组件在模块顶层使用了不稳定的导出方式。

// vite.config.js 示例
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
  plugins: [react()],
});

调试时打开浏览器控制台，查看 [HMR] 和 [Fast Refresh] 相关日志。如果增加了新的 Hook 或修改了不兼容的导出，日志中通常会出现 Fast Refresh had to perform a full reload 的提示。React DevTools 的组件高亮功能也可以辅助观察哪些组件在保存后被重新挂载，通过分析差距定位签名变化来源。

在团队开发中，建议把 Hook 规则纳入 ESLint 校验，并开启 react-refresh/only-export-components 规则。该规则会提示组件文件中不要导出非组件内容，从提交阶段就减少状态丢失的可能。把这些约束固化到 CI 或本地 lint 流程里，HMR 的状态保留能力才能在多人协作中持续发挥价值。