React 19 HMR在Hello-World项目中的异常问题求助

问题本质 #

你遇到的两个问题核心都是HMR配置或代码逻辑不符合React 19的热更新规范：

• 修改代码后报错，多是因为模块更新时未正确处理组件更新边界，或缺少必要的HMR依赖插件
• 页面直接重载，是因为HMR无法识别可热更新的模块，最终 fallback 到全页刷新

分步解决 #

1. 完善webpack配置 #

确保webpack.config.js包含以下关键配置，启用React专用HMR支持：

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

module.exports = {
  mode: 'development',
  devServer: {
    hot: true, // 强制开启热替换
    client: {
      overlay: true, // 显示报错浮层，方便排查问题
    },
  },
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: [
          {
            loader: 'babel-loader',
            options: {
              presets: ['@babel/preset-react'],
              plugins: [require.resolve('react-refresh/babel')], // 注入React刷新插件
            },
          },
        ],
      },
    ],
  },
  plugins: [
    new webpack.HotModuleReplacementPlugin(), // webpack原生HMR插件
    new ReactRefreshWebpackPlugin(), // React专属HMR插件
  ],
};

2. 修正入口文件HMR逻辑 #

React 19的HMR需要配合react-refresh的Runtime API，避免手动操作DOM导致报错。替换index.js代码为：

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { RefreshRuntime } from 'react-refresh/runtime';

const root = createRoot(document.getElementById('root'));

function renderApp() {
  root.render(<App />);
}

renderApp();

// 开发环境下处理HMR
if (module.hot && process.env.NODE_ENV === 'development') {
  // 初始化React Refresh Runtime
  RefreshRuntime.injectIntoGlobalHook(window);
  window.$RefreshReg$ = () => {};
  window.$RefreshSig$ = () => (type) => type;

  module.hot.accept('./App.js', () => {
    // 用startTransition包裹更新，避免更新时的报错
    React.startTransition(() => {
      renderApp();
    });
  });
}

3. 确保依赖版本兼容 #

检查package.json中的核心依赖，保证和React 19版本匹配：

{
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@babel/core": "^7.24.0",
    "@babel/preset-react": "^7.24.0",
    "@pmmmwh/react-refresh-webpack-plugin": "^0.5.11",
    "babel-loader": "^9.1.3",
    "react-refresh": "^0.14.0",
    "webpack": "^5.90.0",
    "webpack-cli": "^5.1.4",
    "webpack-dev-server": "^5.0.0"
  }
}

4. 清理缓存重启服务 #

• 删除node_modules和package-lock.json（或yarn.lock）
• 重新执行npm install
• 重启webpack-dev-server

关键注意事项 #

• 不要手动卸载根组件再重新挂载，React 19的HMR会自动处理组件更新逻辑
• 确保所有React组件文件无语法错误，语法错误会触发全页刷新
• 仅在development模式下启用HMR，生产模式下热更新逻辑会失效

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