Vite HMR 热更新失效或不触发怎么排查？

Question

仓乃文 · Accepted Answer

Vite 的 HMR 失效通常不是 Vite 本身的 Bug，而是文件不在模块图内、插件拦截了更新、或浏览器 WebSocket 连接断开。按以下步骤排查，基本都能定位原因。

排查清单：
```bash
# 1. 检查浏览器控制台是否有 WebSocket 连接错误
# 常见报错：WebSocket connection to "ws://localhost:5173/" failed
# → 检查是否有代理或防火墙拦截
# → 检查 server.hmr.port 是否被占用

# 2. 检查文件是否在 Vite 的模块图内
# 直接在浏览器访问该文件，如果 404 说明路径配置有问题

# 3. 检查 Docker/WSL 环境下的文件监听
# Docker 和 WSL 的文件系统事件默认不传递到宿主机
```

WSL/Docker 环境修复：
```typescript
// vite.config.ts
export default defineConfig({
  server: {
    watch: {
      usePolling: true,
      interval: 100,
    },
    hmr: {
      port: 5173,
      overlay: true,
    },
  },
});
```

其他常见原因：
```
1. 修改了 .env 文件但 HMR 不触发
   → .env 文件修改需要重启 dev server，这是设计如此

2. 修改了 index.html 不触发更新
   → Vite 对 HTML 的 HMR 是整页刷新，检查是否有插件干扰

3. 组件修改了但页面没更新
   → 检查组件是否正确使用了 accept
   → Vue/React 插件会自动处理，但纯 JS 模块需要手动：
   if (import.meta.hot) {
     import.meta.hot.accept((newModule) => {});
   }

4. 修改文件后终端显示 hmr update 但浏览器没反应
   → 清除浏览器缓存后重试
   → 检查是否有 Service Worker 拦截了请求
```