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

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

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 的编译流程。

• 无构建延迟，保存后 200ms 内即可看到效果
• 无需配置 html-webpack-plugin，也无需折腾 devServer
• 但其局限性也很明显：无法处理 import、require、CSS-in-JS 等依赖 Webpack 的特性，仅适用于纯静态页面的开发场景
• 如果混合使用，切勿同时开启 Live Server 和 webpack-dev-server——端口冲突只是小事，浏览器里两个监听器相互干扰，行为完全不可预测

归根结底，真正困扰开发者的并非“如何配置”这一操作，而是许多人默认 HTML 是 Webpack 的一等公民——实际上它只是一个模板，Webpack 根本不关心它是否发生变化，除非你明确告诉它：“喂，盯着点这里”。