React Fast Refresh 搭配 Webpack 5 失效：修改组件触发整页刷新

问题场景 #

使用React Fast Refresh和Webpack 5开发时，修改组件代码后页面会触发整页刷新，而非仅更新变更的组件，无法实现预期的热更新效果。

问题根源 #

该问题由Webpack配置不当导致，以下是经过验证的正确配置方案：

正确配置示例 #

1. 依赖安装 #

先确保安装必要的开发依赖：

npm install -D react-refresh @pmmmwh/react-refresh-webpack-plugin babel-loader @babel/preset-env @babel/preset-react html-webpack-plugin

2. Webpack 核心配置（webpack.config.js） #

const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
    clean: true,
  },
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env', '@babel/preset-react'],
            plugins: [
              // 必须添加该插件以支持组件热更新
              require.resolve('react-refresh/babel'),
            ],
          },
        },
      },
      // 可根据项目需求添加CSS、图片等资源的loader配置
    ],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './public/index.html',
    }),
    // 仅在开发环境启用React Refresh插件
    process.env.NODE_ENV === 'development' && new ReactRefreshWebpackPlugin(),
  ].filter(Boolean),
  devServer: {
    hot: true, // 核心：必须开启热更新
    open: true,
    static: path.join(__dirname, 'public'),
    historyApiFallback: true,
  },
  resolve: {
    extensions: ['.js', '.jsx'],
  },
};

核心注意点 #

• 必须确保devServer.hot设置为true，这是热更新触发的前提
• React Refresh插件仅在开发模式下启用，避免生产环境引入无用代码
• Babel配置中必须加入react-refresh/babel插件，否则组件无法被正确处理以支持热更新
• 不要单独启用hotOnly而关闭hot，两者配合才能保证热更新逻辑正常运行

内容的提问来源于stack exchange，提问作者Yohanna