Webpack HMR与热重载失效：JS/HTML修改无法自动更新浏览器

问题背景 #

正在进行The Odin Project的Restaurant Page项目，使用Webpack打包代码。修改src/index.js或src/template.html后，必须重启npm start启动的开发服务器，浏览器才会更新，需要实现Hot Module Replacement (HMR)或热重载无需重启即可生效。

预期行为 #

修改并保存index.js或template.html后，浏览器自动同步变更。

实际行为 #

保存JS或HTML文件不会触发浏览器更新，浏览器控制台显示：

[webpack-dev-server] Server started: Hot Module Replacement enabled,
Live Reloading enabled, Progress disabled, Overlay enabled.
index.js:577 [HMR] Waiting for update signal from WDS...

已尝试方案 #

• 将devServer.watchFiles从["../src/template.html"]改为["../src/*"]，期望检测src下所有文件变更，但无效。
• 清理缓存、重启服务器，在Firefox(v135.0)和Chrome(v132.0.6834.160)中测试，问题依旧。
• 验证修改webpack.config.js会触发终端更新，但修改JS/HTML文件无反应。

目录结构 #

.
├── dist
│   ├── index.html
│   └── main.js
├── package-lock.json
├── package.json
├── src
│   ├── index.js
│   ├── style.css
│   └── template.html
└── webpack.config.js

配置文件 #

webpack.config.js #

const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");

module.exports = {
  mode: "development",
  entry: "./src/index.js",
  output: {
    filename: "main.js",
    path: path.resolve(__dirname, "dist"),
    clean: true,
  },
  devtool: "eval-source-map",
  devServer: {
    static: './dist',
    watchFiles: ['./src/*'],
    hot: true,
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: "./src/template.html",
      title: 'Development',
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
      {
        test: /\.html$/i,
        loader: "html-loader",
      },
      {
        test: /\.(png|svg|jpg|jpeg|gif)$/i,
        type: "asset/resource",
      },
    ],
  },
};

package.json #

{
  "name": "restaurant-page",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "watch": "webpack --watch",
    "start": "webpack serve --open",
    "build": "webpack"
  },
  "devDependencies": {
    "css-loader": "^7.1.2",
    "html-loader": "^5.1.0",
    "html-webpack-plugin": "^5.6.3",
    "style-loader": "^4.0.0",
    "webpack": "^5.97",
    "webpack-cli": "^6.0.1",
    "webpack-dev-server": "^5.2.0"
  }
}

问题 #

• Webpack配置是否存在问题，导致HMR或热重载无法正常工作？
• 如何确保JS和HTML修改无需重启服务器即可自动触发浏览器更新？

解决方案 #

1. 修正watchFiles路径与配置 #

将devServer中的watchFiles改为绝对路径并匹配所有src下的文件，同时显式开启live reload作为HMR的 fallback：

devServer: {
  static: './dist',
  watchFiles: [path.resolve(__dirname, 'src/**/*')], // 匹配src下所有文件及子目录
  hot: true,
  liveReload: true,
},

使用绝对路径可避免相对路径解析误差，src/**/*能覆盖src目录下所有层级的文件变更。

2. 添加JS模块HMR接受逻辑 #

在src/index.js顶部加入以下代码，让Webpack可以处理JS模块的热替换：

if (module.hot) {
  module.hot.accept();
}

此代码允许Webpack在模块更新时无需刷新页面即可替换模块。

3. 验证HTML模板监听 #

由于已配置watchFiles覆盖src/template.html，结合HtmlWebpackPlugin，模板文件变更时Webpack会自动重新生成dist/index.html并触发浏览器更新。

完成以上修改后，重启开发服务器，修改并保存index.js或template.html，浏览器将自动同步变更。

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