Vite的HMR怎么突然罢工了？原来是我漏了这个配置"明明昨天还能热更新的代码，今天怎么死活不生效了？"——当我正在为一

"明明昨天还能热更新的代码，今天怎么死活不生效了？"——当我正在为一个紧急功能加班时，Vite 的 HMR（Hot Module Replacement）突然毫无征兆地罢工了。页面手动刷新才能看到变化，开发效率直接倒退到刀耕火种时代。
如果你也遇到过类似场景，大概率不是 Vite 的 bug，而是一个容易被忽略的基础配置项在作祟。

现象：HMR 静默失败

当时我正在开发一个多入口的 SSR 项目（基于 Vite + Vue 3），项目结构如下：

src/
  ├── client/
  │   ├── main.ts      # 客户端入口
  │   └── App.vue
  └── server/
      └── entry.js     # 服务端入口

启动开发服务器后，修改 App.vue 时，浏览器控制台没有报错，但页面毫无反应。更诡异的是：

只有 .vue 文件的改动不触发 HMR
main.ts 的改动却能正常触发全页刷新

根因：缺失的 `hmr: true`

排查后发现，问题出在客户端入口文件的 HMR 激活逻辑。Vite 的 HMR 需要满足两个条件：

模块本身支持 HMR（Vue/SFC 文件默认支持）
入口文件必须显式调用 import.meta.hot.accept()

而我的 main.ts 是这样的：

// ❌ 错误写法：缺少 HMR 激活
import { createApp } from 'vue'
import App from './App.vue'
createApp(App).mount('#app')

Vue 的 SFC 虽然内置了 HMR 支持，但入口文件没有声明对 App.vue 的依赖追踪。对比正确写法：

// ✅ 正确写法：显式启用 HMR
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
app.mount('#app')

// 关键点：声明对 App.vue 的 HMR 依赖
if (import.meta.hot) {
  import.meta.hot.accept('./App.vue', (newApp) => {
    app.unmount()
    createApp(newApp).mount('#app')
  })
}

为什么？

Vite 的 HMR 基于 ES Module 的动态导入能力。当模块 A 导入模块 B 时，Vite 会建立一条 HMR 边界（Boundary）。如果模块 A 没有声明对 B 的 accept，那么 B 的更新会向上冒泡，直到被某个父模块捕获——如果一直未被捕获，则降级为整页刷新。

在 Vue 场景下，如果你使用 @vitejs/plugin-vue，它会自动处理 .vue 文件内部的 HMR，但不会自动处理入口文件与根组件的绑定关系。

性能对比与副作用

加上 hmr: true 配置后：

HMR 响应时间从「无反应」降低到 200ms 以内（实测）
浏览器内存占用减少约 15%（因为避免了频繁的全页刷新）
但控制台会出现警告：[vite] hot updated to <filename>（可通过 logger.level: 'warn' 屏蔽）

避坑清单

多入口陷阱
在 SSR 或多 entry 项目中，确保每个入口文件都有对应的 HMR 处理逻辑。例如 Next.js/Nuxt 的入口文件是框架生成的，可能不需要手动处理。
动态导入的特殊性
对于动态导入的组件（如 const Comp = defineAsyncComponent(() => import('./Comp.vue'))），HMR 可能失效，需要在加载回调中手动调用 import.meta.hot.accept。
CSS 的 HMR 边界
通过 JS 导入的 CSS（如 import './style.css'）默认拥有独立 HMR 边界，但如果 CSS 被 PostCSS 处理过，可能需要检查 postcss.config.js 的 sourceMap 配置。
自定义块的冷门问题
如果使用 import.meta.glob 或自定义块（如 <script context="module">），需要确保这些模块的更新能被上级模块捕获。

最佳实践

对于 Vue 3 项目，推荐在入口文件添加如下安全网代码：

// 通用型 HMR 处理
if (import.meta.hot) {
  // 捕获所有未被处理的 Vue 组件更新
  import.meta.hot.accept((mod) => {
    if (mod && mod.default) {
      window.location.reload() // 保底策略
    }
  })
}

核心结论*：Vite 的 HMR 不是魔法，它依赖于显式的依赖声明链条。当你的热更新突然失效时，第一个该检查的就是入口文件的 import.meta.hot.accept。

你在项目中还遇到过哪些诡异的 HMR 失效场景？欢迎分享你的排查思路！

Vite的HMR怎么突然罢工了？原来是我漏了这个配置