craco配置React开发模式热刷新后页面无法交互问题排查

1. 热更新插件冲突 #

• 诱因：老项目常同时安装了已废弃的react-hot-loader和CRA内置的react-refresh-webpack-plugin，两个插件逻辑冲突会导致热更新后组件树挂载不完整，DOM渲染正常但事件绑定全部丢失，无法交互。
• 解决：
  • 执行npm uninstall react-hot-loader卸载冗余依赖，删除代码里所有import { hot } from 'react-hot-loader/root'之类的相关引用
  • 检查craco.config.js的webpack配置项，删除手动引入的ReactRefreshWebpackPlugin配置，CRA 4.0+版本已经内置该插件，重复引入会直接触发冲突。

2. devServer热更新参数配置错误 #

• 诱因：手动修改craco的devServer配置时错误关闭了热更新模式、或者同时开启hot和liveReload触发重复刷新，部分项目会手动关闭错误遮罩overlay，导致热更新时的组件报错被隐藏，页面渲染半崩溃状态无法交互。
• 解决：调整craco.config.js中的devServer配置为以下正确形式：

module.exports = {
  // 其他配置...
  devServer: {
    hot: true,
    liveReload: false, // 开启HMR时必须关闭liveReload，避免触发重复整页刷新
    client: {
      overlay: true // 保持错误遮罩开启，热更新报错时会直接提示，不会渲染异常状态的页面
    }
  }
}

3. 入口文件或根组件不符合Fast Refresh识别规则 #

• 诱因：自定义根节点挂载逻辑、入口文件未导出可被热更新追踪的组件、或者根节点外层包裹的全局逻辑（比如全局事件拦截、权限判断）在热更新时重复执行，会导致事件绑定异常。
• 解决：
  • 调整入口文件写法，不要在根渲染逻辑外写全局事件绑定、SDK初始化等逻辑，这类逻辑要放到根组件的useEffect中加空依赖确保只执行一次
  • 不要给根组件加匿名函数包裹，确保Fast Refresh能定位到组件声明，参考正确入口写法：

// src/index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);

4. 全局资源重复注入拦截交互 #

• 诱因：热更新时如果重复注入全屏透明遮罩（比如弹层组件、加载组件未正确卸载）、重复绑定全局键盘/鼠标事件阻止默认行为，会出现页面内容可见但所有操作被拦截的情况。
• 排查&解决：
  出现交互失效时直接打开浏览器开发者工具，在Elements面板查看DOM树顶层是否存在未正常卸载的全屏透明节点，在Event Listeners面板检查click、keydown事件是否存在重复绑定上百次的异常项，定位到对应业务代码或第三方SDK后，给初始化逻辑加单次执行限制即可。

快速定位技巧 #

如果暂时找不到问题点，先临时注释掉craco.config.js里所有自定义webpack、babel、devServer配置，启动项目测试热更新是否恢复正常，如果恢复就逐个放开配置项，重点排查自定义babel插件中与React JSX编译相关的配置（比如手动配置@babel/plugin-transform-react-jsx但未开启runtime: 'automatic'也会导致Fast Refresh失效），以及低版本craco对React 18的适配问题——React 18项目必须把@craco/craco升级到7.0以上版本，低版本存在已知的热更新适配bug。

内容的提问来源于stack exchange，提问作者Gokul.M