HMR API

注意

这是客户端 HMR API。有关在插件中处理 HMR 更新的信息，请参阅 handleHotUpdate。

手动 HMR API 主要面向框架和工具作者。作为最终用户，HMR 很可能已经在框架特定的入门模板中为您处理好了。

Vite 通过特殊的 import.meta.hot 对象公开其手动 HMR API

interface ImportMeta {
  readonly hot?: ViteHotContext
}

interface ViteHotContext {
  readonly data: any

  accept(): void
  accept(cb: (mod: ModuleNamespace | undefined) => void): void
  accept(dep: string, cb: (mod: ModuleNamespace | undefined) => void): void
  accept(
    deps: readonly string[],
    cb: (mods: Array<ModuleNamespace | undefined>) => void,
  ): void

  dispose(cb: (data: any) => void): void
  prune(cb: (data: any) => void): void
  invalidate(message?: string): void

  on<T extends string>(
    event: T,
    cb: (payload: InferCustomEventPayload<T>) => void,
  ): void
  off<T extends string>(
    event: T,
    cb: (payload: InferCustomEventPayload<T>) => void,
  ): void
  send<T extends string>(event: T, data?: InferCustomEventPayload<T>): void
}

必需条件保护

首先，确保使用条件块保护所有 HMR API 使用，以便代码可以在生产环境中进行树摇。

if (import.meta.hot) {
  // HMR code
}

TypeScript 的 IntelliSense

Vite 在 vite/client.d.ts 中为 import.meta.hot 提供类型定义。您可以在 src 目录中创建一个 env.d.ts，以便 TypeScript 获取类型定义

/// <reference types="vite/client" />

hot.accept(cb)

要使模块自我接受，请使用 import.meta.hot.accept 并传入一个回调函数，该函数接收更新后的模块

export const count = 1

if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    if (newModule) {
      // newModule is undefined when SyntaxError happened
      console.log('updated: count is now ', newModule.count)
    }
  })
}

接受热更新的模块被视为 **HMR 边界**。

Vite 的 HMR 实际上不会交换最初导入的模块：如果 HMR 边界模块从依赖项重新导出导入，那么它负责更新这些重新导出（并且这些导出必须使用 let）。此外，从边界模块向上链的导入者不会收到更改通知。这种简化的 HMR 实现足以满足大多数开发用例，同时允许我们跳过生成代理模块的昂贵工作。

Vite 要求此函数的调用在源代码中以 import.meta.hot.accept(（对空格敏感）的形式出现，以便模块接受更新。这是 Vite 进行静态分析以启用模块的 HMR 支持的要求。

hot.accept(deps, cb)

模块也可以接受来自直接依赖项的更新，而无需重新加载自身

import { foo } from './foo.js'

foo()

if (import.meta.hot) {
  import.meta.hot.accept('./foo.js', (newFoo) => {
    // the callback receives the updated './foo.js' module
    newFoo?.foo()
  })

  // Can also accept an array of dep modules:
  import.meta.hot.accept(
    ['./foo.js', './bar.js'],
    ([newFooModule, newBarModule]) => {
      // The callback receives an array where only the updated module is
      // non null. If the update was not successful (syntax error for ex.),
      // the array is empty
    },
  )
}

hot.dispose(cb)

自我接受的模块或期望被其他模块接受的模块可以使用 hot.dispose 来清理其更新副本创建的任何持久副作用

function setupSideEffect() {}

setupSideEffect()

if (import.meta.hot) {
  import.meta.hot.dispose((data) => {
    // cleanup side effect
  })
}

hot.prune(cb)

注册一个回调函数，当模块不再在页面上被导入时调用。与 hot.dispose 相比，如果源代码在更新时自行清理副作用，而您只需要在模块从页面中删除时进行清理，则可以使用此函数。Vite 目前在 .css 导入中使用它。

function setupOrReuseSideEffect() {}

setupOrReuseSideEffect()

if (import.meta.hot) {
  import.meta.hot.prune((data) => {
    // cleanup side effect
  })
}

hot.data

import.meta.hot.data 对象在同一更新模块的不同实例之间持久化。它可以用来将信息从模块的先前版本传递到下一个版本。

请注意，不支持对 data 本身进行重新赋值。相反，您应该修改 data 对象的属性，以便从其他处理程序添加的信息得以保留。

// ok
import.meta.hot.data.someValue = 'hello'

// not supported
import.meta.hot.data = { someValue: 'hello' }

hot.decline()

这目前是一个空操作，用于向后兼容。如果将来有新的用途，这可能会改变。要指示模块不可热更新，请使用 hot.invalidate()。

hot.invalidate(message?: string)

自我接受的模块可能在运行时意识到它无法处理 HMR 更新，因此需要将更新强制传播到导入者。通过调用 import.meta.hot.invalidate()，HMR 服务器将使调用者的导入者失效，就好像调用者没有自我接受一样。这将在浏览器控制台和终端中记录一条消息。您可以传递一条消息来提供有关失效原因的一些上下文。

请注意，即使您计划立即之后调用 invalidate，也应该始终调用 import.meta.hot.accept，否则 HMR 客户端将不会监听对自我接受模块的未来更改。为了清楚地传达您的意图，我们建议您在 accept 回调函数中调用 invalidate，如下所示

import.meta.hot.accept((module) => {
  // You may use the new module instance to decide whether to invalidate.
  if (cannotHandleUpdate(module)) {
    import.meta.hot.invalidate()
  }
})

hot.on(event, cb)

监听 HMR 事件。

以下 HMR 事件由 Vite 自动分派

• 'vite:beforeUpdate' 当要应用更新时（例如，模块将被替换）
• 'vite:afterUpdate' 当更新刚刚应用时（例如，模块已被替换）
• 'vite:beforeFullReload' 当要进行完全重新加载时
• 'vite:beforePrune' 当要修剪不再需要的模块时
• 'vite:invalidate' 当使用 import.meta.hot.invalidate() 使模块失效时
• 'vite:error' 当发生错误时（例如，语法错误）
• 'vite:ws:disconnect' 当 WebSocket 连接断开时
• 'vite:ws:connect' 当 WebSocket 连接（重新）建立时

自定义 HMR 事件也可以从插件中发送。有关更多详细信息，请参阅 handleHotUpdate。

hot.off(event, cb)

从事件监听器中删除回调函数。

hot.send(event, data)

将自定义事件发送回 Vite 的开发服务器。

如果在连接之前调用，数据将被缓冲并在连接建立后发送。

有关更多详细信息，请参阅 客户端-服务器通信。

进一步阅读

如果您想了解有关如何使用 HMR API 及其工作原理的更多信息，请查看以下资源

• 热模块替换很简单