热重载

注意 — HMR API 仍在开发中。一些功能缺失。可以通过将 development 选项设置为 { hmr: false } 在 Bun.serve 中禁用 HMR。

import.meta.hot.accept()

accept() 方法表明一个模块可以被热替换。当被调用时 不带参数，它表明这个模块可以通过简单地 重新评估文件来替换。在热更新之后，这个模块的导入者将被 自动修补。

import { getCount } from "./foo.ts";

console.log("count is ", getCount());

import.meta.hot.accept();

export function getNegativeCount() {
  return -getCount();
}

这为 index.ts 导入的所有文件创建了一个热重载边界。这意味着无论何时 foo.ts 或其任何依赖项被保存， 更新将冒泡到 index.ts 并重新评估。导入 index.ts 的文件将被修补以导入新版本的 getNegativeCount()。如果只有 index.ts 被更新，则只有这一个文件会被 重新评估，并且 foo.ts 中的计数器将被重用。

这可以与 import.meta.hot.data 结合使用，以在 前一个模块和新模块之间传输状态。

当没有模块调用 import.meta.hot.accept() (并且没有 React Fast Refresh 或插件为你调用它)，当文件 更新时，页面将重新加载，并且控制台警告会显示哪些文件已失效。这个警告 如果依赖于完整页面重新加载更有意义，则可以安全地忽略它。

使用回调函数

当提供一个回调函数时，import.meta.hot.accept 将像在 Vite 中那样工作。它不会修补这个模块的导入者，而是调用 带有新模块的回调函数。

export const count = 0;

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

建议使用不带参数的 import.meta.hot.accept()，因为它通常使您的代码更易于理解。

接受其他模块

import { count } from "./foo";

import.meta.hot.accept("./foo", () => {
  if (!newModule) return;

  console.log("updated: count is now ", count);
});

表明可以接受依赖项的模块。当依赖项更新时，将使用新模块调用回调函数。

使用多个依赖项

import.meta.hot.accept(["./foo", "./bar"], newModules => {
  // newModules is an array where each item corresponds to the updated module
  // or undefined if that module had a syntax error
});

表明可以接受多个依赖项的模块。此变体接受一个依赖项数组，其中回调函数将接收更新后的模块，以及对于任何有错误的模块接收 undefined。

import.meta.hot.data

import.meta.hot.data 在热 替换期间维护模块实例之间的状态，从而可以从旧版本到新版本传输数据。当 import.meta.hot.data 被写入时，Bun 也会将此模块标记为 能够自我接受 (等同于调用 import.meta.hot.accept())。

import { createRoot } from "react-dom/client";
import { App } from "./app";

const root = import.meta.hot.data.root ??= createRoot(elem);
root.render(<App />); // re-use an existing root

在生产环境中，data 被内联为 {}，这意味着它不能用作状态保持器。

建议对有状态模块使用上述模式，因为 Bun 知道它可以将生产环境中的 {}.prop ??= value 缩小为 value。

import.meta.hot.dispose()

附加一个 on-dispose 回调函数。这会在以下情况被调用

• 就在模块被另一个副本替换之前 (在加载下一个副本之前)
• 在模块被分离之后 (移除对此模块的所有导入，参见 import.meta.hot.prune())

const sideEffect = setupSideEffect();

import.meta.hot.dispose(() => {
  sideEffect.cleanup();
});

此回调函数不会在路由导航或浏览器标签页关闭时被调用。

返回一个 Promise 将延迟模块替换，直到模块被处理。 所有 dispose 回调函数都是并行调用的。

import.meta.hot.prune()

附加一个 on-prune 回调函数。当对此模块的所有导入都 被移除，但模块之前已被加载时，会调用此回调函数。

这可以用于清理在模块 加载时创建的资源。与 import.meta.hot.dispose() 不同，这与 accept和 data 更好地配合使用，以管理有状态的资源。一个管理 WebSocket 的完整示例

import { something } from "./something";

// Initialize or re-use a WebSocket connection
export const ws = (import.meta.hot.data.ws ??= new WebSocket(location.origin));

// If the module's import is removed, clean up the WebSocket connection.
import.meta.hot.prune(() => {
  ws.close();
});

如果改为使用 dispose，则 WebSocket 将在每次 热更新时关闭并重新打开。这两个版本的代码都将防止在导入的 文件更新时页面重新加载。

import.meta.hot.on() 和 off()

on() 和 off() 用于监听来自 HMR 运行时的事件。事件名称带有前缀，以便插件之间不会相互冲突。

import.meta.hot.on("bun:beforeUpdate", () => {
  console.log("before a hot update");
});

当文件被替换时，其所有事件监听器都会被自动移除。

所有内置事件的列表

为了与 Vite 兼容，上述事件也可以通过 vite:* 前缀而不是 bun:* 来使用。