前端工程化 / 系统课时

调整 HMR 与文件监听

调整 HMR 与文件监听

本课处理两类常见故障:浏览器无法连接 HMR WebSocket,以及文件已经保存但 Vite 没有感知变化。你将分别配置客户端可达的 WebSocket 地址和轮询监听,并建立从文件事件到页面更新的定位顺序。

学习目标

  • 为反向代理或容器环境设置 HMR WebSocket 的协议、主机、端口和路径
  • 在原生监听失效时有条件地启用文件轮询
  • 根据日志区分监听故障、WebSocket 故障和模块热更新边界

先拆开两条独立链路

HMR 能成功需要两条链路同时工作。第一条是文件系统链路:编辑器写入文件,监听器产生变更事件,Vite 重新转换受影响模块。第二条是网络链路:浏览器通过 WebSocket 接收更新消息,再替换模块或执行整页刷新。

容器挂载、WSL2、网络盘和某些同步目录容易丢失原生文件事件,此时页面完全收不到更新。反向代理、HTTPS 终止或端口映射则更容易破坏 WebSocket,即使 Vite 已经检测到文件变化,浏览器仍无法接收消息。

Vite HMR 与文件监听的两条链路

配置外部可达的 WebSocket

当前 Vite 配置中,HMR 错误遮罩仍由 server.hmr 控制,而 WebSocket 的地址类参数推荐写在 server.ws。旧版把 host、port、clientPort 等字段放在 server.hmr 的写法仍可能兼容,但已不适合作为新配置。

下面假设浏览器访问 https://dev.example.test,反向代理把普通 HTTP 和 /vite-hmr WebSocket 都转发到容器内的 5173。clientPort: 443 表示浏览器连接外部 HTTPS 端口,而不是容器内部端口。

ts
import { defineConfig } from 'vite'

const usePolling = process.env.VITE_USE_POLLING === '1'

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5173,
    strictPort: true,
    hmr: {
      // 保留错误遮罩,关闭它只会隐藏错误,不会修复连接
      overlay: true,
    },
    ws: {
      protocol: 'wss',
      host: 'dev.example.test',
      clientPort: 443,
      path: '/vite-hmr',
      timeout: 30_000,
    },
    watch: {
      // 仅在容器挂载或网络盘丢事件时启用,避免长期空转
      usePolling,
      interval: 200,
      ignored: ['**/.git/**', '**/dist/**', '**/coverage/**'],
      awaitWriteFinish: {
        stabilityThreshold: 300,
        pollInterval: 100,
      },
    },
  },
})

host 与 clientPort 必须站在浏览器视角填写;port 若单独设置,则代表 WebSocket 服务端实际监听端口。path 必须与反向代理转发路径一致。页面经 HTTPS 打开时通常使用 wss,否则浏览器可能拦截混合内容。

配置反向代理升级连接

下面是 Nginx 位置块片段,依赖已有的 server 配置和名为 vite 的上游。关键点是使用 HTTP/1.1,并转发 WebSocket 升级头。

nginx
# 片段示例:放入已有的 Nginx server 块
location /vite-hmr {
    proxy_pass http://vite;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 60s;
}

生效行为是浏览器访问 wss://dev.example.test/vite-hmr 时,由 Nginx 将连接升级并转发到 Vite。若代理改写了路径,必须同步修改 server.ws.path,否则普通页面能打开而 HMR 会持续重连。

启动并验证文件监听

在容易丢失文件事件的环境中,通过环境变量按需打开轮询。动态耗时、局域网地址和端口以实际环境为准。

bash
VITE_USE_POLLING=1 npm run dev -- --debug hmr

预期输出会包含开发服务器地址;保存一个已被页面引用的源码文件后,还应出现 HMR 更新日志。

text
VITE v<VERSION> ready in <TIME> ms
Local:   http://localhost:5173/
Network: http://<HOST>:5173/
<...> [vite] (client) hmr update <PATH>

浏览器开发者工具的 Network 面板中还应存在状态为 101 Switching Protocols 的 /vite-hmr WebSocket。日志中的路径、时间和主机地址会因项目而不同。

按现象定位根因

终端完全没有文件变更日志时,先检查文件是否真的写入 Vite 所在文件系统,再临时启用 usePolling。轮询会周期性扫描文件,CPU 和磁盘开销更高,因此应缩小项目目录、排除生成目录,并尽量把源码放到容器或 WSL2 的原生文件系统。

终端有 HMR 更新日志,但浏览器反复出现 WebSocket 连接失败时,检查外部协议、域名、端口和路径,同时确认代理支持 WebSocket 升级。端口可能被 Vite 自动递增时,clientPort 会与真实端口错位,因此反向代理场景通常同时启用 strictPort: true。

WebSocket 已连接却发生整页刷新,不一定是网络问题。某些模块没有被框架或插件接受热替换,或者循环依赖导致执行顺序无法安全恢复,Vite 会退回整页刷新;可继续使用 --debug hmr 查看更新边界。

使用轮询的边界

不要在所有开发机上永久启用高频轮询。先优先使用原生监听,并确认编辑器、Vite 与项目目录位于同一文件系统;只有容器卷、网络盘或跨系统编辑确实丢事件时,再启用轮询。

awaitWriteFinish 会等待文件大小稳定后再发出事件,适合网络盘或会分段写入文件的工具,但会增加更新延迟。参数应从较宽松数值开始,再根据实际保存耗时逐步缩短。

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

目录与阅读设置

阅读设置

17

记录一个想法

调整 HMR 与文件监听

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

登录哪都通