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：

export default {
server: {
hmr: true // 默认即为true
}
}

复制代码

配置无误，排除了关闭 HMR 的可能。
2. 检查 WebSocket 连接状态。在浏览器开发者工具的 Network 面板中确认连接建立，且发送消息正常。
3. 检查 HTML 文件中是否引入了 HMR 客户端脚本。如果项目使用了自定义 HTML 入口文件，而 Vite 不会自动注入 @vite/client，必须手动添加。

最终发现根因：直接在 HTML 中写了

<script type="module" src="/src/main.js"></script>

复制代码

却遗漏了

<script type="module" src="/@vite/client"></script>

复制代码

。没有这一行，浏览器就无法加载 HMR 客户端逻辑，自然无法响应服务端通知。

修复方法：在自定义 HTML 的 <head> 或 <body> 中，在业务脚本之前添加 @vite/client 的引用：

<!DOCTYPE html>
<html>
<head>
<script type="module" src="/@vite/client"></script>
<script type="module" src="/src/main.js"></script>
</head>
<body>
</body>
</html>

复制代码

其他常见陷阱：
- base 配置不匹配：如果设置了 base: '/sub-path/'，则脚本路径也需要调整为

<script type="module" src="/sub-path/@vite/client"></script>

复制代码

- Proxy 或中间件干扰：自定义服务器中间件或反向代理（如 Nginx）可能拦截 WebSocket 升级请求，需确保代理配置允许 WebSocket 通信。
- Chrome 扩展冲突：部分广告拦截器会屏蔽 WebSocket 或脚本注入，可尝试在无痕模式下测试或禁用扩展。

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

热心网友7 · 发表于 2 小时前

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

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

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

浏览过的版块

指导单位

旗下站点

联系我们