Vite HMR API 详解

很久之前，我们是通过 live reload 也就是自动刷新页面的方式来解决的。不过随着前端工程的日益庞大，开发场景也越来越复杂，这种live reload的方式在诸多的场景下却显得十分鸡肋，简单来说就是模块局部更新+状态保存的需求在live reload的方案没有得到满足，从而导致开发体验欠佳。

live reload 实现方案

如果在改动代码后，想要进行模块级别的局部更新该怎么做呢？业界一般使用 HMR 技术来解决这个问题，像 Webpack、Parcel 这些传统的打包工具底层都实现了一套 HMR API，而我们今天要讲的就是 Vite 自己所实现的 HMR API。相比于传统的打包工具，Vite 的 HMR API 基于 ESM 模块规范来实现，可以达到毫秒级别的更新速度，性能非常强悍。

什么是 HMR？

HMR 的全称叫做Hot Module Replacement，即模块热替换或者模块热更新。在计算机领域当中也有一个类似的概念叫热插拔，我们经常使用的 USB 设备就是一个典型的代表，当我们插入 U 盘的时候，系统驱动会加载在新增的 U 盘内容，不会重启系统，也不会修改系统其它模块的内容。HMR 的作用其实一样，就是在页面模块更新的时候，直接把页面中发生变化的模块替换为新的模块，同时不会影响其它模块的正常运作。

Vite HMR 的优势

特性	说明
⚡ 闪电级更新	利用浏览器缓存机制，避免重新打包
🎯 精确更新	仅更新变动的模块及其依赖
🔥 原生 ESM	无需打包即可实现模块热替换
🛠️ 灵活 API	支持自定义 HMR 处理逻辑

必需的条件守卫

所有 HMR API 必须包裹在条件语句中，确保生产环境被 Tree-shaking 优化：

javascript 复制代码

if (import.meta.hot) {
  // HMR 相关逻辑
}

核心 API 详解

1. `import.meta.hot.accept()` - 接受模块更新

定义模块更新的处理逻辑，是 HMR 的核心方法。分为三种使用场景：

1.1 接受自身更新

适用于无依赖的独立模块（如工具函数）：

javascript 复制代码

let count = 0;

// 模块自身更新时触发
import.meta.hot.accept((newModule) => {
  // 新模块加载后的回调
  console.log("模块已更新", newModule);
  // 手动恢复状态
  newModule.setCount(count);
});

export function setCount(val) {
  count = val;
}

1.2 接受单个依赖更新

监听指定子模块变更（如 UI 组件）：

javascript 复制代码

import { render } from './render.js';

// 当 './render.js' 更新时触发
import.meta.hot.accept('./render.js', (newRender) => {
  // 清理旧组件
  document.body.innerHTML = '';
  // 使用新模块渲染
  newRender.render();
});

1.3 接受多个依赖更新

批量处理多个子模块变更：

javascript 复制代码

import { A } from './A.js';
import { B } from './B.js';

// 当 A 或 B 更新时触发
import.meta.hot.accept(
  ['./A.js', './B.js'],
  ([newA, newB]) => {
    console.log('A 或 B 已更新');
    // 更新依赖逻辑
    newA.init();
    newB.init();
  }
);

注意事项：

回调函数参数是更新后的模块对象
若未指定依赖路径（无参），当前模块成为 HMR 边界
若指定依赖路径，当前模块不再是 HMR 边界

2. `import.meta.hot.dispose()` - 清理副作用

在模块被替换前执行清理操作（如移除事件监听/定时器）：

javascript 复制代码

// 初始化定时器
const timer = setInterval(() => {
  console.log("Running...");
}, 1000);

// 模块卸载前的清理
import.meta.hot.dispose(() => {
  clearInterval(timer); // 清除定时器
  console.log("模块已被卸载");
});

注意事项：

必须清理所有副作用（事件监听、网络请求等）
与 import.meta.hot.data 配合可实现状态持久化

3. `import.meta.hot.data` - 跨更新状态持久化

在模块更新间共享数据：

javascript 复制代码

// 初始化数据
if (!import.meta.hot.data.cache) {
  import.meta.hot.data.cache = {
    count: 0,
    user: { name: "Alice" }
  };
}

// 更新数据
import.meta.hot.data.cache.count++;

// 获取持久化数据
console.log("当前计数:", import.meta.hot.data.cache.count);

注意事项：

数据存储在内存中，刷新页面会重置
适合保存非序列化数据（如函数实例）

4. `import.meta.hot.invalidate()` - 强制刷新页面

当模块无法处理更新时，降级为整页刷新：

javascript 复制代码

import.meta.hot.accept((newModule) => {
  // 连续更新超过 10 次则刷新页面
  if (import.meta.hot.data.updateCount >= 10) {
    import.meta.hot.invalidate(); // 触发页面刷新
  }
  // 记录更新次数
  import.meta.hot.data.updateCount = 
    (import.meta.hot.data.updateCount || 0) + 1;
});

注意事项：

应作为异常处理的最后手段
调用后当前模块及依赖树会被完全替换

5. `import.meta.hot.on()` - 监听 HMR 事件

监听 Vite 内置或自定义事件：

javascript 复制代码

// 监听 Vite 内置事件
import.meta.hot.on('vite:beforeUpdate', (event) => {
  console.log('即将更新模块:', event.updates);
});

// 监听自定义事件（其他模块触发）
import.meta.hot.on('custom:event', (data) => {
  console.log('收到自定义事件:', data);
});

常用内置事件：

事件名称	触发时机
`vite:beforeUpdate`	模块即将被替换前
`vite:beforeFullReload`	完整页面刷新即将发生
`vite:error`	发生错误（如语法错误）
`vite:invalidate`	某模块调用 `hot.invalidate()` 时

6. `import.meta.hot.off()` - 移除事件监听

取消已注册的事件监听器：

javascript 复制代码

function handleUpdate(event) {
  console.log("更新信息:", event);
}

// 添加监听
import.meta.hot.on('vite:beforeUpdate', handleUpdate);

// 移除监听
import.meta.hot.off('vite:beforeUpdate', handleUpdate);

关键注意事项

仅开发环境有效
import.meta.hot 在生产构建时会被完全移除，无需额外配置。

状态管理限制

javascript 复制代码

// 错误示例：直接更新未持久化的变量
let state = { count: 0 };
import.meta.hot.accept(() => {
  // 更新后 state 会被重置！
  console.log(state.count); // 总是 0
});

解决方案 ：通过 import.meta.hot.data 持久化状态。

不可枚举性
console.log(import.meta) 不会显示 hot 属性，需显式访问：
javascript 复制代码
```
console.log(import.meta.hot); // 正确
```
循环依赖处理

避免模块间的循环依赖，可能导致 HMR 失效。

CSS 的特殊性

CSS 模块默认支持 HMR 无需额外代码，但通过 JS 动态注入的样式需手动处理：

javascript 复制代码

import styles from './styles.css?inline';

// 动态注入样式
const styleEl = document.createElement('style');
styleEl.textContent = styles;
document.head.append(styleEl);

// 更新时替换样式
import.meta.hot.accept('./styles.css', (newStyles) => {
  styleEl.textContent = newStyles;
});

第三方库兼容

部分库需手动启用 HMR（如 Vue/React 组件）：

javascript 复制代码

// Vue 组件示例
import { createApp } from 'vue';
import App from './App.vue';

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

// 启用 Vue HMR
import.meta.hot.accept('./App.vue', () => {
  app.unmount();
  app.mount('#app');
});

实战示例

场景：计数器组件保留状态热更新

javascript 复制代码

// counter.js
export let count = 0;

// 初始化或恢复状态
if (import.meta.hot?.data.count) {
  count = import.meta.hot.data.count;
}

// 点击事件（副作用需清理）
function handleClick() {
  count++;
  document.getElementById('count').textContent = count;
}
document.getElementById('btn').addEventListener('click', handleClick);

// HMR 处理
if (import.meta.hot) {
  // 持久化计数状态
  import.meta.hot.dispose(() => {
    import.meta.hot.data.count = count;
  });
  
  // 清理事件监听
  import.meta.hot.dispose(() => {
    document.getElementById('btn')
      .removeEventListener('click', handleClick);
  });
  
  // 接受自身更新
  import.meta.hot.accept();
}

通过此配置，修改 counter.js 中的逻辑时，计数状态将被保留，事件监听器正确更新。

调试技巧

在浏览器控制台查看 HMR 状态：
javascript 复制代码
```
console.log(import.meta.hot.data);
```
强制查看所有 HMR API：
javascript 复制代码
```
console.dir(import.meta.hot);
```

手动触发更新检查：

javascript 复制代码

import.meta.hot.send('vite:invalidate', { path: '/src/main.js' });

掌握这些 API 能显著提升开发体验，尤其适合大型项目状态复杂场景。更多细节参考 Vite 官方 HMR 文档。

Vite HMR API 详解