查看: 89|回复: 1

Vite HMR热更新失效排查:自定义HTML缺少@vite/client引用的修复方法

[复制链接]
发表于 2 小时前 | 显示全部楼层 |阅读模式
Vite 的 HMR(热模块替换)是提升开发效率的关键特性,但如果遇到修改代码后页面不再自动刷新,浏览器控制台也看不到 [vite] hot updated 日志,而手动刷新才能生效的情况,很可能是 HMR 客户端注入出了问题。本文记录一次深入排查的过程和解决方案。

HMR 的基本流程:Vite 通过文件监听检测到改动 -> 分析依赖 -> 通过 WebSocket 向浏览器发送更新通知 -> 浏览器端的 HMR 客户端加载新模块完成替换。其中浏览器端的 @vite/client 脚本是核心组件。

问题现象:WebSocket 连接正常建立(状态码 101),甚至能看到服务端发出的更新消息(如 { type: 'update', path: '/src/main.js' }),但页面就是不自动刷新。说明服务端通知已发出,但浏览器端没有正确响应。

排查步骤:
1. 检查 vite.config.js 是否显式禁用了 HMR:
  1. export default {
  2.   server: {
  3.     hmr: true // 默认即为true
  4.   }
  5. }
复制代码
配置无误,排除了关闭 HMR 的可能。
2. 检查 WebSocket 连接状态。在浏览器开发者工具的 Network 面板中确认连接建立,且发送消息正常。
3. 检查 HTML 文件中是否引入了 HMR 客户端脚本。如果项目使用了自定义 HTML 入口文件,而 Vite 不会自动注入 @vite/client,必须手动添加。

最终发现根因:直接在 HTML 中写了
  1. <script type="module" src="/src/main.js"></script>
复制代码
却遗漏了
  1. <script type="module" src="/@vite/client"></script>
复制代码
。没有这一行,浏览器就无法加载 HMR 客户端逻辑,自然无法响应服务端通知。

修复方法:在自定义 HTML 的 <head> 或 <body> 中,在业务脚本之前添加 @vite/client 的引用:
  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4.   <script type="module" src="/@vite/client"></script>
  5.   <script type="module" src="/src/main.js"></script>
  6. </head>
  7. <body>
  8. </body>
  9. </html>
复制代码

其他常见陷阱:
- base 配置不匹配:如果设置了 base: '/sub-path/',则脚本路径也需要调整为
  1. <script type="module" src="/sub-path/@vite/client"></script>
复制代码
- Proxy 或中间件干扰:自定义服务器中间件或反向代理(如 Nginx)可能拦截 WebSocket 升级请求,需确保代理配置允许 WebSocket 通信。
- Chrome 扩展冲突:部分广告拦截器会屏蔽 WebSocket 或脚本注入,可尝试在无痕模式下测试或禁用扩展。

这次经历提醒我们,Vite 的“约定优于配置”虽然简化了开发,但自定义项目结构时务必关注隐式依赖。如果 HMR 突然失效,优先检查 HTML 中是否包含了 @vite/client。
回复

使用道具 举报

发表于 2 小时前 | 显示全部楼层

Re: Vite HMR热更新失效排查:自定义HTML缺少@vite/client引用的修复方法

感谢分享,这个排查过程很清晰。我自己也遇到过类似问题,尤其是用自定义HTML模板时容易忽略这个隐式依赖。你提到的 base 路径和代理干扰点也很关键,之前因为 Nginx 没配 WebSocket 升级踩过坑。以后 HMR 失效就按这个顺序查了,非常实用!
回复 支持 反对

使用道具 举报

您需要登录后才可以回帖 登录 | 注册

本版积分规则

指导单位

江苏省公安厅

江苏省通信管理局

浙江省台州刑侦支队

DEFCON GROUP 86025

Hacking Group 021A

旗下站点

态势感知中心

应急响应中心

红盟安全

联系我们

官方QQ群:112851260

官方邮箱:security#ihonker.org(#改成@)

官方核心成员

关注微信公众号

Archiver|手机版|小黑屋| ( 沪ICP备2021026908号 )

GMT+8, 2026-6-11 21:53 , Processed in 0.039631 second(s), 17 queries , Gzip On, Redis On.

Powered by ihonker.com

Copyright © 2015-现在.

  • 返回顶部