Hono.js 与 Bun 运行时中 WebSocket 服务的注意事项

在使用 Hono.js 框架结合 Bun 运行时开发 WebSocket 应用时，开发者可能会遇到一个看似奇怪的现象：应用在热重载模式下运行正常，但在普通模式下却会抛出端口占用错误。这种现象背后其实隐藏着 Bun 运行时模块加载机制与 Hono.js 服务启动方式的微妙交互。

问题现象分析

当开发者编写一个典型的 Hono.js WebSocket 服务时，通常会采用以下结构：

1. 创建 Hono 应用实例并配置 WebSocket 路由
2. 使用 Bun.serve 启动服务
3. 导出应用实例（常见于模块化开发习惯）

在热重载模式下(--hot)，Bun 的模块系统会特殊处理导出内容，因此服务能正常运行。但在普通模式下，Bun 会尝试自动加载模块的默认导出并启动服务，这就导致了双重服务启动的问题。

根本原因

问题的核心在于 Bun 运行时的两个特性：

1. 自动服务加载：当模块有默认导出且导出对象包含 fetch 方法时，Bun 会尝试自动启动服务
2. 模块导出行为：在普通执行模式下，模块导出会触发自动服务加载机制

当代码中同时存在显式的 Bun.serve 调用和默认导出时，实际上创建了两个服务实例，自然会导致端口冲突。

解决方案

解决这个问题的方法很简单：移除不必要的默认导出。在大多数 Hono.js 应用中，特别是当直接使用 Bun.serve 时，并不需要导出应用实例。

正确的代码结构应该是：

import { Hono } from "hono";
import { createBunWebSocket } from "hono/bun";

const { websocket, upgradeWebSocket } = createBunWebSocket();

const app = new Hono().get(
  "/ws",
  upgradeWebSocket((_) => {
    return {
      onOpen(evt, ws) {
        console.log("Connection open");
        ws.send("Hello, World!");
      },
      onMessage(evt, ws) {
        ws.send("You said: " + evt.data);
      },
      onClose(evt, ws) {
        console.log("Connection closed");
      },
    };
  })
);

Bun.serve({
  fetch: app.fetch,
  port: 3000,
  websocket,
});

最佳实践建议

1. 明确服务启动方式：选择要么通过 Bun 自动加载，要么显式调用 Bun.serve，不要混用
2. 生产环境注意事项：生产部署时应使用显式服务启动方式，避免依赖运行时的自动行为
3. 模块化设计：如果需要模块化组织代码，可以考虑将应用实例创建与服务启动逻辑分离
4. 环境区分：开发时可以利用热重载的便利性，但生产构建时要确保代码结构正确

深入理解

这种现象实际上反映了现代 JavaScript 运行时对模块系统处理的差异。Bun 的设计初衷是简化开发流程，因此加入了自动服务加载这样的便利特性。然而，这种"魔法"行为有时会与显式代码产生冲突，特别是在涉及网络服务等需要精确控制的场景下。

理解这一机制对于全栈开发者尤为重要，它提醒我们在享受现代工具便利性的同时，也要注意其背后的工作原理，这样才能写出更加健壮可靠的应用程序。