前端工程化 / 系统课时

定位 HMR 失效与整页刷新

定位 HMR 失效与整页刷新

本课建立一条可重复执行的 HMR 排查路径:先确认文件变更是否被监听,再检查浏览器 WebSocket、模块更新边界、循环依赖、框架插件与副作用,最终把“没有更新”和“被迫整页刷新”分开处理。

学习目标

  • 根据终端、浏览器和页面状态判断 HMR 故障所在层级
  • 使用 HMR 调试日志识别更新边界与循环依赖
  • 修复框架插件、代理链路和模块副作用导致的异常

按现象确定故障层

先保存一个当前页面必然会使用的源文件,再同时观察终端、浏览器控制台和页面状态。终端没有任何文件变更记录,优先检查监听范围、容器挂载、WSL 文件系统和导入路径大小写;终端有记录但浏览器无消息,转查 HMR WebSocket;浏览器收到更新却整页刷新,则重点检查更新边界、循环依赖和插件处理。

Vite HMR 分层排查流程

Vite 检测到文件变化却不更新时,导入路径大小写不一致也是高频原因;在大小写不敏感的开发机上暂时可用,进入 Linux 或严格文件系统后会暴露。:contentReference[oaicite:0]{index=0}

检查更新边界与循环依赖

HMR 更新会沿模块导入链向上寻找可接受更新的边界。Vue、React 等项目通常由官方框架插件建立边界;普通模块只有在框架或手动 HMR API 能接住更新时,才可以避免页面状态被清空。没有处理者时,整页刷新是恢复正确状态的兜底行为。

先用调试日志复现一次问题:

bash
npm run dev -- --debug hmr

预期输出:

text
<DEBUG_PREFIX> hmr update <PATH>
<DEBUG_PREFIX> circular imports detected: <PATH> -> <PATH>

实际日志前缀、路径和是否出现循环依赖提示会随项目及 Vite 版本不同。若日志只显示文件变化,没有可接受边界,检查该文件是否经过正确的框架插件;若出现循环路径,沿日志拆分双向导入,常见做法是把共享常量、类型或纯函数下沉到第三个无副作用模块。Vite 官方排障文档明确指出:更新未被 Vite 或插件处理,以及 HMR 链路中存在循环依赖,都可能触发整页刷新;vite --debug hmr 可用于输出循环依赖路径。:contentReference[oaicite:1]{index=1}

检查框架插件和模块副作用

确认项目使用与框架匹配的官方插件,并检查插件是否因条件配置而未启用。例如 Vue 单文件组件需要 Vue 插件,React Fast Refresh 需要 React 插件;只安装依赖但没有把插件加入 plugins,文件仍可能被普通 JavaScript 流程处理。手动编写 import.meta.hot 主要面向框架或工具作者,业务项目通常应先修复官方插件链路。:contentReference[oaicite:2]{index=2}

页面能局部更新但事件触发次数不断增加,通常不是 HMR 失效,而是旧模块留下了副作用。重点排查全局事件监听、定时器、WebSocket、状态订阅和第三方实例:创建时要有对应销毁逻辑,并在模块替换前通过框架卸载钩子或 import.meta.hot.dispose 清理。不要把模块顶层注册动作写成“只会执行一次”的假设。

检查 WebSocket 与代理链路

打开浏览器开发者工具的 Network 面板并筛选 WS。若没有 HMR 连接、连接持续失败,或页面通过 HTTPS 访问却尝试连接明文 WebSocket,检查反向代理是否转发升级请求,以及 server.hmr 的 protocol、host、port 或 clientPort 是否与浏览器实际入口一致。

不要一开始就硬编码 server.hmr。本地直连正常、经过网关才失败时,才根据公开访问地址修正客户端连接参数;同时检查代理是否保留 Upgrade 和 Connection 头。修复后应看到 WebSocket 保持连接,保存文件时收到更新消息,页面状态不再因普通组件修改而重置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定位 HMR 失效与整页刷新

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通