Bun热重载指南：--watch与--hot模式对比、import.meta.hot API详解

Bun Hot Reloading by secondsky/claude-skills

98 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/secondsky/claude-skills --skill 'Bun Hot Reloading'

Node.js 开发性能优化

🇨🇳中文介绍

Bun 热重载

Bun 提供内置的热重载功能，以加速开发周期。

监听模式与热模式对比

功能特性	`--watch`	`--hot`
行为	重启进程	重载模块
状态	重载时丢失	保留
速度	约 20ms 重启	即时重载
使用场景	任意文件类型	Bun.serve HTTP 服务

监听模式 (--watch)

当文件变更时，重启整个进程。

# 基础监听模式
bun --watch run src/index.ts

# 监听特定脚本
bun --watch run dev

# 配合测试运行器使用
bun --watch test

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

812,900 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

269,400 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

218,000 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

147,400 周安装

自动监听导入的文件
任何 .ts、.tsx、.js、.jsx 文件的变更都会触发
同时监听 .json 导入
以全新状态重启

// 检查热重载是否可用
if (import.meta.hot) {
  // 接受对此模块的更新
  import.meta.hot.accept();

  // 带回调地接受更新
  import.meta.hot.accept((newModule) => {
    console.log("模块已更新:", newModule);
  });

  // 重载前的清理工作
  import.meta.hot.dispose(() => {
    // 关闭连接、清除定时器等
    clearInterval(myInterval);
  });

  // 拒绝热重载（强制完全重启）
  import.meta.hot.decline();

  // 使此模块失效（触发父模块重载）
  import.meta.hot.invalidate();
}

// src/server.ts
import { createApp } from "./app";

const app = createApp();

const server = Bun.serve({
  port: 3000,
  fetch: app.fetch,
});

// 热重载：重新创建应用
if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    // 使用新的 fetch 处理器重载
    server.reload({
      fetch: newModule.default.fetch,
    });
  });
}

// src/server.ts
// 存储在 globalThis 中以在重载后存活
globalThis.connections ??= new Set();

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response(`连接数: ${globalThis.connections.size}`);
  },
  websocket: {
    open(ws) {
      globalThis.connections.add(ws);
    },
    close(ws) {
      globalThis.connections.delete(ws);
    },
  },
});

if (import.meta.hot) {
  import.meta.hot.accept();
}

// dev-server.ts
import { watch } from "fs";

const srcDir = "./src";
let server: ReturnType<typeof Bun.serve> | null = null;

async function startServer() {
  // 动态导入，附带缓存破坏
  const module = await import(`./src/server.ts?t=${Date.now()}`);

  if (server) {
    server.stop();
  }

  server = Bun.serve(module.default);
  console.log(`服务器已启动，端口 ${server.port}`);
}

// 初始启动
await startServer();

// 监听变更
watch(srcDir, { recursive: true }, async (event, filename) => {
  if (filename?.endsWith(".ts") || filename?.endsWith(".tsx")) {
    console.log(`\n[${event}] ${filename}`);
    await startServer();
  }
});

console.log("正在监听变更...");

// src/dev-server.ts
const clients = new Set<ServerWebSocket>();

const server = Bun.serve({
  port: 3000,
  fetch(req, server) {
    if (req.headers.get("upgrade") === "websocket") {
      server.upgrade(req);
      return;
    }

    // 在开发环境中注入重载脚本
    const html = `
      <!DOCTYPE html>
      <html>
        <body>
          <h1>Hello!</h1>
          <script>
            const ws = new WebSocket('ws://localhost:3000');
            ws.onmessage = (e) => {
              if (e.data === 'reload') location.reload();
            };
          </script>
        </body>
      </html>
    `;
    return new Response(html, {
      headers: { "Content-Type": "text/html" },
    });
  },
  websocket: {
    open(ws) {
      clients.add(ws);
    },
    close(ws) {
      clients.delete(ws);
    },
  },
});

// 文件变更时通知客户端
watch("./src", { recursive: true }, () => {
  clients.forEach((ws) => ws.send("reload"));
});

// 检查是否以 --hot 模式运行
const isHot = !!import.meta.hot;

// 检查是否以 --watch 模式运行
const isWatch = process.env.BUN_WATCH === "1";

// 开发模式
const isDev = process.env.NODE_ENV !== "production";

if (isDev) {
  console.log("运行在开发模式");
  console.log(`热重载: ${isHot}`);
  console.log(`监听模式: ${isWatch}`);
}

错误	原因	修复方法
`变更未检测到`	文件未被导入	检查导入链
`状态丢失`	使用了 `--watch`	使用 `--hot` 或 globalThis
`端口被占用`	服务器未停止	实现 server.stop()
`内存泄漏`	未进行清理	使用 dispose 回调

🇺🇸English

Bun Hot Reloading

Bun provides built-in hot reloading for faster development cycles.

Watch Mode vs Hot Mode

Feature	`--watch`	`--hot`
Behavior	Restart process	Reload modules
State	Lost on reload	Preserved
Speed	~20ms restart	Instant reload
Use case	Any file type	Bun.serve HTTP

Watch Mode (--watch)

Restarts the entire process when files change.

# Basic watch mode
bun --watch run src/index.ts

# Watch specific script
bun --watch run dev

# Watch with test runner
bun --watch test

package.json Scripts

{
  "scripts": {
    "dev": "bun --watch run src/index.ts",
    "dev:server": "bun --watch run src/server.ts",
    "test:watch": "bun --watch test"
  }
}

Watch Behavior

Watches imported files automatically
Triggers on any .ts, .tsx, .js, .jsx change
Also watches .json imports
Restarts with fresh state

Hot Mode (--hot)

Reloads modules in-place without restarting the process.

bun --hot run src/server.ts

HTTP Server Hot Reload

// src/server.ts
let counter = 0; // State preserved across hot reloads

export default {
  port: 3000,
  fetch(req: Request) {
    counter++;
    return new Response(`Request #${counter}`);
  },
};



bun --hot run src/server.ts

When you modify server.ts, the module reloads instantly while counter keeps its value.

Bun.serve with Hot Reload

// src/server.ts
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello!");
  },
});

// Hot reload handler
if (import.meta.hot) {
  import.meta.hot.accept(() => {
    console.log("Hot reload!");
  });
}

console.log(`Server running on port ${server.port}`);

import.meta.hot API

// Check if hot reload is available
if (import.meta.hot) {
  // Accept updates to this module
  import.meta.hot.accept();

  // Accept with callback
  import.meta.hot.accept((newModule) => {
    console.log("Module updated:", newModule);
  });

  // Cleanup before reload
  import.meta.hot.dispose(() => {
    // Close connections, clear intervals, etc.
    clearInterval(myInterval);
  });

  // Decline hot reload (force full restart)
  import.meta.hot.decline();

  // Invalidate this module (trigger parent reload)
  import.meta.hot.invalidate();
}

HTTP Server Patterns

Express-like Pattern

// src/server.ts
import { createApp } from "./app";

const app = createApp();

const server = Bun.serve({
  port: 3000,
  fetch: app.fetch,
});

// Hot reload: recreate app
if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    // Reload with new fetch handler
    server.reload({
      fetch: newModule.default.fetch,
    });
  });
}

Stateful Server

// src/server.ts
// Store in globalThis to survive reloads
globalThis.connections ??= new Set();

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response(`Connections: ${globalThis.connections.size}`);
  },
  websocket: {
    open(ws) {
      globalThis.connections.add(ws);
    },
    close(ws) {
      globalThis.connections.delete(ws);
    },
  },
});

if (import.meta.hot) {
  import.meta.hot.accept();
}

Custom Watch Implementation

// dev-server.ts
import { watch } from "fs";

const srcDir = "./src";
let server: ReturnType<typeof Bun.serve> | null = null;

async function startServer() {
  // Dynamic import with cache busting
  const module = await import(`./src/server.ts?t=${Date.now()}`);

  if (server) {
    server.stop();
  }

  server = Bun.serve(module.default);
  console.log(`Server started on port ${server.port}`);
}

// Initial start
await startServer();

// Watch for changes
watch(srcDir, { recursive: true }, async (event, filename) => {
  if (filename?.endsWith(".ts") || filename?.endsWith(".tsx")) {
    console.log(`\n[${event}] ${filename}`);
    await startServer();
  }
});

console.log("Watching for changes...");

WebSocket Live Reload

Server

// src/dev-server.ts
const clients = new Set<ServerWebSocket>();

const server = Bun.serve({
  port: 3000,
  fetch(req, server) {
    if (req.headers.get("upgrade") === "websocket") {
      server.upgrade(req);
      return;
    }

    // Inject reload script in dev
    const html = `
      <!DOCTYPE html>
      <html>
        <body>
          <h1>Hello!</h1>
          <script>
            const ws = new WebSocket('ws://localhost:3000');
            ws.onmessage = (e) => {
              if (e.data === 'reload') location.reload();
            };
          </script>
        </body>
      </html>
    `;
    return new Response(html, {
      headers: { "Content-Type": "text/html" },
    });
  },
  websocket: {
    open(ws) {
      clients.add(ws);
    },
    close(ws) {
      clients.delete(ws);
    },
  },
});

// Notify clients on file change
watch("./src", { recursive: true }, () => {
  clients.forEach((ws) => ws.send("reload"));
});

Vite Integration

For frontend development with HMR:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    hmr: true,
  },
});



# Use Bun to run Vite
bunx --bun vite

Testing with Watch

# Watch tests
bun --watch test

# Watch specific file
bun --watch test src/utils.test.ts

# With bail (stop on first failure)
bun --watch test --bail

Environment Detection

// Check if running with --hot
const isHot = !!import.meta.hot;

// Check if running with --watch
const isWatch = process.env.BUN_WATCH === "1";

// Development mode
const isDev = process.env.NODE_ENV !== "production";

if (isDev) {
  console.log("Running in development mode");
  console.log(`Hot reload: ${isHot}`);
  console.log(`Watch mode: ${isWatch}`);
}

Common Issues

State Not Preserved

// ❌ State lost on hot reload
let cache = new Map();

// ✅ State preserved on hot reload
globalThis.cache ??= new Map();
const cache = globalThis.cache;

Cleanup Not Running

// ❌ Interval keeps running after reload
setInterval(() => console.log("tick"), 1000);

// ✅ Clean up on dispose
const interval = setInterval(() => console.log("tick"), 1000);

if (import.meta.hot) {
  import.meta.hot.dispose(() => {
    clearInterval(interval);
  });
}

Module Not Reloading

// ❌ Import not watched
const config = require("./config.json");

// ✅ Use import for watching
import config from "./config.json";

Common Errors

Error	Cause	Fix
`Changes not detected`	File not imported	Check import chain
`State lost`	Using `--watch`	Use `--hot` or globalThis
`Port in use`	Server not stopped	Implement server.stop()
`Memory leak`	No cleanup	Use dispose callback

When to Load References

Load references/advanced-hmr.md when:

Custom HMR protocols
Module federation
Complex state management

Load references/debugging.md when:

HMR not working
State issues
Performance debugging

Weekly Installs

–

Repository

secondsky/claude-skills

GitHub Stars

First Seen

–

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Bun热重载指南：--watch与--hot模式对比、import.meta.hot API详解

🇨🇳中文介绍

Bun 热重载

监听模式与热模式对比

监听模式 (--watch)

相关 Skills

package.json 脚本

监听行为

热模式 (--hot)

HTTP 服务器热重载

使用热重载的 Bun.serve

import.meta.hot API

HTTP 服务器模式

类 Express 模式

有状态服务器

自定义监听实现

WebSocket 实时重载

服务器端

Vite 集成

使用监听模式进行测试

环境检测

常见问题

状态未保留

清理未执行

模块未重载

常见错误

何时加载参考文档

🇺🇸English

Bun Hot Reloading

Watch Mode vs Hot Mode

Watch Mode (--watch)

package.json Scripts

Watch Behavior

Hot Mode (--hot)

HTTP Server Hot Reload

Bun.serve with Hot Reload

import.meta.hot API

HTTP Server Patterns

Express-like Pattern

Stateful Server

Custom Watch Implementation

WebSocket Live Reload

Server

Vite Integration

Testing with Watch

Environment Detection

Common Issues

State Not Preserved

Cleanup Not Running

Module Not Reloading

Common Errors

When to Load References

最新 Skills