根本原因是CSS模块未纳入HMR依赖图；必须通过style-loader注入且由JS显式import，禁用MiniCssExtractPlugin开发配置，确保路径大小写一致并透传WebSocket头。
热更新失效导致整页刷新，根本原因只有一个：CSS 模块没被纳入 HMR 依赖图，构建工具无法识别它是可热替换的模块。
style-loader 缺失或未生效
CSS 要走 HMR，必须由 style-loader 接管注入逻辑——它把 CSS 编译成 JS 模块，才能被 Webpack 的 HMR 运行时捕获和替换。如果配置里用了 MiniCssExtractPlugin.loader（哪怕只在开发环境误配），或者漏掉了 style-loader，CSS 就会退化为静态资源，变更只能触发 liveReload 整页刷新。
- 检查
webpack.config.js中module.rules对 CSS 的处理链，确保开发环境是['style-loader', 'css-loader']，而非[MiniCssExtractPlugin.loader, 'css-loader'] - 确认没有在
mode: 'development'下也启用了MiniCssExtractPlugin—— 它天生不支持 HMR - 若用 Vite，检查是否误加了
css.devSourcemap = true等非常规配置，某些版本会干扰 HMR 注入时机
入口 JS 没 import CSS 文件
Webpack 的 HMR 只监听「被 import/require 进依赖图」的文件。HTML 中直接 <link rel="stylesheet"> 引入的 CSS，完全游离在打包系统之外，修改后 devServer 根本收不到变更通知。
- 所有样式文件必须通过 JS 入口显式导入，例如：
import './index.css';或import '@/styles/main.scss'; - Parcel 用户尤其注意：它虽默认支持 CSS HMR，但前提是 CSS 必须从 JS 文件中
import，而不是靠 HTML 的<link> - Next.js 用户需确认是否启用了
styled-jsx或css-in-js方案——它们走的是 JS 运行时样式注入，HMR 行为取决于具体库实现，不是 Webpack 原生路径
devServer 配置切断了 HMR 通道
即使 CSS 被正确 import，HMR 仍可能静默失败。常见断点是 WebSocket 连接未建立，浏览器收不到更新指令，最终 fallback 到整页刷新。
立即学习“前端免费学习笔记（深入）”；
- 启动前设置环境变量：
WDS_SOCKET_HOST=localhost、WDS_SOCKET_PORT=3000（与devServer.port一致） - 检查控制台是否有
[WDS] Hot Module Replacement enabled.日志；若无，大概率是hot: true未生效，或被命令行参数（如--live-reload）覆盖 - 使用 Nginx 反代时，必须透传
Upgrade和Connection头，否则 WebSocket 握手失败
真正容易被忽略的点是：HMR 对路径大小写极其敏感。比如磁盘上是 components/Button.css，但 JS 里写成 import './Components/Button.css'，Webpack watcher 就不会触发变更，连日志都不会报错——它只是安静地跳过了这个路径。
