排查 Webpack 热更新失效，最忌讳一上来就反复开关 hot 字段。HMR 链路其实横跨编译配置、文件监听和浏览器运行时三个环节，任何一个环节被阻断，都会出现保存后页面无反应、控制台报错，或者干脆退化成整页刷新。本文把每个环节拆开，说明最容易被忽略的原因。
一、先检查配置层：hot、publicPath 和入口边界
配置层最容易出现的问题，是把热更新理解为只与 devServer.hot 有关。实际上热更新能否生效取决于三个配置共同作用：devServer.hot、output.publicPath 以及入口模块是否在 HMR 覆盖范围内。Webpack 5 中开启 hot: true 会自动注入 HotModuleReplacementPlugin，但在自定义 compiler 或多 compiler 场景下，仍建议显式添加 new webpack.HotModuleReplacementPlugin()，避免遗漏。
一个常见的隐蔽问题是 output.publicPath。热更新文件通常命名为 [name].[hash].hot-update.js 和 hot-update.json，它们会以 publicPath 作为前缀从浏览器请求。如果 publicPath 被设置成相对路径 ./ 或指向了 CDN 目录，而页面实际从根路径加载资源，运行时就会请求到错误地址，控制台出现 404，表现为每次保存后编译成功但界面不变化。排查时打开 Network 面板，过滤 hot-update，看这些请求是否返回正常。
多入口项目还要注意，HMR 只对入口模块的依赖图生效，对 HTML 模板、静态文件或不被 import 的资源不产生模块替换。例如使用 html-webpack-plugin 时修改 index.html 文字，默认不会触发热替换，需要配合 watchFiles 让 devServer 监听模板目录，或依赖 html-webpack-plugin 自身触发重新加载。此时页面可能发生整页刷新，这不算 HMR 失效，但需要和真正的模块替换区分开。
const webpack = require('webpack');
module.exports = {
entry: './src/index.js',
output: {
publicPath: '/'
},
devServer: {
hot: true,
watchFiles: ['src/**/*.js', 'src/**/*.css', 'public/**/*.html']
},
plugins: [
new webpack.HotModuleReplacementPlugin()
]
};
上面这份配置把 publicPath 设为根路径，并让 devServer 额外监控模板文件。如果你使用的是 webpack-dev-server 3.x，还需要注意 contentBase 与 static 的差异，避免静态资源路径错误间接导致热更新请求被当成普通资源处理。
二、确认文件监听是否真的捕获到变更
如果编译层配置没问题，但终端没有新的编译输出，问题通常出在文件监听。Webpack 和 devServer 底层依赖 Node.js 的 fs.watch，在 Docker、虚拟机共享目录、Windows 网络盘或某些旧 Linux 内核上，inotify 数量限制会导致事件丢失。此时最直接的解决方式是改用轮询。可以在 watchFiles 或 watchOptions 中设置 usePolling: true，并调整轮询间隔，虽然会增加 CPU 占用，但能保证监听到变更。
另一个常见原因是编辑器的安全写入策略。VS Code 等编辑器默认可能使用原子保存，先写入临时文件再重命名，Webpack 在文件重命名间隙读取时可能得到空内容或旧内容，而聚合超时时间 aggregateTimeout 设置过短，就会漏掉这次更新。建议把 aggregateTimeout 调整到 200 到 500 毫秒，给文件系统缓冲时间。对于网络目录，同时配合 poll 和较长间隔可以显著减少假失效。
module.exports = {
devServer: {
hot: true,
watchFiles: {
paths: ['src/**/*'],
options: {
usePolling: true,
interval: 300,
aggregateTimeout: 300
}
}
}
};
缓存也会造成“看起来没监听到”。Webpack 5 的持久化缓存、babel-loader 的 cacheDirectory 以及一些自建 loader 缓存，可能让变更后的模块仍然命中旧缓存，尤其是修改了配置文件或 loader 选项后。排查时可以删除 node_modules/.cache 下的缓存目录，重新启动 devServer，观察问题是否消失。如果消失，说明缓存键没有包含影响结果的参数，需要修正缓存配置。
三、从浏览器端反查 HMR 运行时
编译成功、监听正常但页面不动，问题往往移到浏览器端。先看浏览器控制台的 HMR 日志。Webpack 5 默认会在控制台输出类似 [HMR] Waiting for update signal from WDS... 和 [HMR] Checking for updates on the server...。如果一直卡在等待更新，说明 WebSocket 连接没有建立。检查 devServer.client.webSocketURL 是否配置为可访问的地址，尤其当 devServer 通过 Nginx 反向代理或 HTTPS 访问时，默认的 ws://localhost:8080 可能被跨域或混合内容策略拦截。
WebSocket 正常但每次保存都整页刷新，通常是因为修改的模块没有被 module.hot.accept 接纳。CSS 文件之所以能无损热替换，是因为 style-loader 在其内部调用了 accept；而普通 JavaScript 模块如果没有写 accept，HMR 运行时只能选择整页刷新。想让某个函数或组件的修改只触发热替换，需要在该模块或其父模块中显式声明依赖。
// render.js
export function render() {
const root = document.getElementById('app');
root.innerHTML = new Date().toLocaleTimeString();
}
// index.js
import { render } from './render';
render();
if (module.hot) {
module.hot.accept('./render', () => {
render();
});
}
这段代码中，index.js 对 ./render 模块执行 accept，当 render.js 变化时只重新执行回调。注意回调里如果只重新调用 render，且 render 内部有 DOM 替换逻辑，需要确保旧 DOM 被清理，否则会出现重复节点。更安全的做法是在模块中通过 module.hot.dispose 清理事件监听、定时器或全局样式，防止每次热替换叠加副作用。
控制台若出现 module.hot.decline 或某个模块被拒绝更新的提示，说明依赖链中有模块明确表示无法热替换，或者存在不确定性副作用。此时需要定位到该模块，评估是否可以在 accept 回调中手动处理更新，或者将副作用隔离到可被 dispose 清理的作用域中。
四、利用排查顺序快速定位问题
当热更新失效时，不建议随机修改配置。可以先按顺序检查四个信号：终端是否重新编译，Network 是否出现 hot-update 请求，WebSocket 是否连接成功，浏览器控制台是否出现 HMR 接受或拒绝日志。四个信号能快速区分问题落在编译层、请求层还是运行时层。比如终端无编译，优先查文件监听；终端有编译但无 hot-update 请求，优先查 publicPath 和入口依赖；有请求但控制台报错，优先查模块 accept 与副作用清理。
如果定位到某一层仍然不确定，可以用最小化复现。新建一个只包含入口文件和一个可更新模块的目录，不引入 babel、ESLint、CSS、HTML 插件等，只保留 devServer.hot 和 HotModuleReplacementPlugin，逐项加回自定义配置。这样做虽然耗时，但能明确问题是由某个 loader 的缓存、某个插件的监听行为还是 IDE 的文件写入方式引起的。
还有一些跨版本差异值得注意。Webpack 4 到 Webpack 5 的 devServer 选项发生了不少变化，例如 contentBase 被 static 取代，hotOnly 被 hot: 'only' 取代。如果在旧项目迁移过程中只升级了 webpack 而没有调整 devServer 配置，热更新可能静默失效。查看官方迁移文档或运行时的 deprecation 警告，往往能发现被忽略的配置项。
Webpack热更新HMR失效devServer配置修改时间：2026-09-30 15:18:57