HTML热更新配置：开发阶段代码自动刷新浏览器

时间：2026-07-19 06:18

html-webpack-plugin默认不监听模板文件，导致修改HTML无法自动刷新。通过配置watchOptions:{poll:1000}可实现轮询检测，或使用webpack-watch-files-plugin手动注入监听。--inline负责全页刷新，--hot仅模块热替换，HTML修改需配合模板监听。LiveServer插件直接监听文件，响应更快

许多前端开发者都曾踩过同一个坑：明明已正确配置了 webpack-dev-server --hot，但修改 index.html 保存后，浏览器却毫无反应。很多人第一反应是热更新未开启，折腾半天才发现——问题根本不在热更新，而是 html-webpack-plugin 默认对模板文件“视而不见”。

HTML热更新配置：实现开发阶段修改代码自动刷新浏览器的方法

html-webpack-plugin 为何不监听 template 文件变更

你或许会感到困惑：明明已经指定了 template: './src/index.html'，为什么修改它后仍无法触发自动刷新？关键在于 html-webpack-plugin 在开发模式下只会将模板“编译一次”，后续的修改根本不会触发 HTML 重新生成。它默认监听的是 entry 入口文件和 chunk 模块的变化，并不关心 template 路径下的文件是否被改动。于是出现了一个极其矛盾的现象：修改 JavaScript 或 CSS 能自动刷新，修改 HTML 却毫无反应，只能手动按 F5。

它仅对入口文件和依赖模块进行文件监视（watch）
即便你明确指定了模板路径，插件也不会自动为其添加监听
最终结果就是：修改模板文件？无任何响应。

启用 template 文件监听的两种可靠方法

要想让 HTML 模板的修改也能加入刷新流程，必须显式开启监听。目前有两种经过验证的可靠方式，推荐优先采用第一种：

在 html-webpack-plugin 实例中传入 watchOptions: { poll: 1000 }，使用轮询检测机制，兼容性最佳，几乎不受文件系统差异影响
或者结合 webpack-config-plugins 与 webpack-watch-files-plugin 手动注入监听逻辑，适用于需要同时监控多个模板的复杂场景
注意：不要依赖 devServer.watchFiles——它仅负责触发 HMR，并不负责 HTML 的重新生成

第一种方案的配置示例：

new HtmlWebpackPlugin({
  template: './src/index.html',
  filename: 'index.html',
  watchOptions: {
    poll: 1000 // 每秒检查一次 template 是否变化
  }
})

webpack-dev-server 中 --inline 与 --hot 参数的区别

--inline 和 --hot 参数看似相似，实则功能截然不同：

--inline 会在打包产物中注入一个客户端脚本，专门负责与 dev server 通信并接收全页刷新指令。简单来说，它管的是“通知浏览器刷新”。
--hot 启用的是 HMR（热模块替换）机制——只替换发生变化的模块，不刷新整个页面。前提是代码中必须包含 module.hot.accept() 或使用了框架的适配器。
对于纯 HTML + JavaScript 项目，--hot 对 HTML 修改完全无效。想要 HTML 修改后自动刷新，必须依赖 --inline 配合模板监听才能生效。
如果项目使用了 React 或 Vue 等框架，--hot 才有实际意义；否则建议关闭它，避免产生误导。

Live Server 插件为何比 webpack-dev-server 更快响应 HTML 修改

VS Code 的 Live Server 插件之所以能够实现“秒刷”HTML，是因为其设计理念截然不同。它本质上是一个轻量级 HTTP 服务器结合文件系统监听器，直接监控整个目录中所有 .html 文件的变动，一旦保存立即发送 location.reload() 指令，完全绕过 Webpack 的编译流程。