Bun热重载指南：--watch与--hot模式详解，提升JavaScript/TypeScript开发效率

The Agent Skills Directory

安装命令

npx skills add https://smithery.ai/skills/secondsky/bun-hot-reloading

🇨🇳中文介绍

Bun 热重载

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

监视模式与热模式

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

监视模式 (--watch)

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

# 基本监视模式
bun --watch run src/index.ts

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

# 使用测试运行器监视
bun --watch test

package.json 脚本

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

监视行为

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

热模式 (--hot)

无需重启进程，原地重载模块。

bun --hot run src/server.ts

HTTP 服务器热重载

// src/server.ts
let counter = 0; // 状态在热重载间保留

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

bun --hot run src/server.ts

当你修改 server.ts 时，模块会即时重载，而 counter 保持其值。

使用热重载的 Bun.serve

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

// 热重载处理器
if (import.meta.hot) {
  import.meta.hot.accept(() => {
    console.log("Hot reload!");
  });
}

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

import.meta.hot API

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

  // 带回调的接受
  import.meta.hot.accept((newModule) => {
    console.log("Module updated:", newModule);
  });

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

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

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

HTTP 服务器模式

类 Express 模式

// 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(`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();
}

自定义监视实现

// 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 started on port ${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("Watching for changes...");

WebSocket 实时重载

服务器

// 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"));
});

Vite 集成

用于前端开发并启用 HMR：

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

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

# 使用 Bun 运行 Vite
bunx --bun vite

使用监视进行测试

# 监视测试
bun --watch test

# 监视特定文件
bun --watch test src/utils.test.ts

# 使用 bail 选项（在首次失败时停止）
bun --watch test --bail

环境检测

// 检查是否使用 --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("Running in development mode");
  console.log(`Hot reload: ${isHot}`);
  console.log(`Watch mode: ${isWatch}`);
}

常见问题

状态未保留

// ❌ 热重载时状态丢失
let cache = new Map();

// ✅ 热重载时状态保留
globalThis.cache ??= new Map();
const cache = globalThis.cache;

清理未运行

// ❌ 重载后定时器继续运行
setInterval(() => console.log("tick"), 1000);

// ✅ 在 dispose 时清理
const interval = setInterval(() => console.log("tick"), 1000);

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

模块未重载

// ❌ 导入未被监视
const config = require("./config.json");

// ✅ 使用 import 以启用监视
import config from "./config.json";

常见错误

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

何时加载参考资料

在以下情况加载 references/advanced-hmr.md：

自定义 HMR 协议
模块联邦
复杂的状态管理

在以下情况加载 references/debugging.md：

HMR 不工作
状态问题
性能调试

每周安装次数

–

来源

smithery.ai/ski…eloading

首次出现

–

🇺🇸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

广告位招租

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

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

联系我们

package.json Scripts

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

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

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}`);

// 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,
    });
  });
}

// 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

// 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"));
});

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

# 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}`);
}

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

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

// ❌ 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";

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

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

109,600 周安装

Bun热重载指南：--watch与--hot模式详解，提升JavaScript/TypeScript开发效率

🇨🇳中文介绍

Bun 热重载

监视模式与热模式

监视模式 (--watch)

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)

相关 Skills

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