FORMA

HTTP 服务器

创建 HTTP 服务器（Bun.serve）

Bun 内置了高性能的 HTTP 服务器，通过 Bun.serve 可以轻松启动服务。从 Bun v1.2.3 开始，推荐使用 routes 对象来定义路由，更加直观和灵活。

一、基础示例（routes 模式）

typescript
// server.ts
const server = Bun.serve({
  routes: {
    // 静态路由
    "/api/status": new Response("OK"),

    // 动态路由，参数自动注入到 req.params
    "/users/:id": (req) => new Response(`Hello User ${req.params.id}!`),

    // 同一路径不同 HTTP 方法
    "/api/posts": {
      GET: () => new Response("List posts"),
      POST: async (req) => {
        const body = await req.json();
        return Response.json({ created: true, ...body });
      },
    },

    // 通配符路由（以 "/api/" 开头的所有路径）
    "/api/*": () => Response.json({ message: "Not found" }, { status: 404 }),

    // 重定向
    "/blog/hello": Response.redirect("/blog/hello/world"),

    // 直接返回静态文件
    "/favicon.ico": Bun.file("./favicon.ico"),
  },

  // 可选：fallback 处理所有未匹配的路由
  // fetch(req) {
  //   return new Response("Not Found", { status: 404 });
  // },
});

console.log(`Server running at ${server.url}`);

运行：

bash
bun --allow-net server.ts

（权限标志 --allow-net 在新版本中可能非必需，但添加可以确保网络权限）

二、处理请求上下文

Bun 的 req 对象是标准 Request 的扩展（BunRequest），提供了便捷的属性和方法：

  • req.params：动态路由参数对象。
  • req.cookies：类似 Map 的 Cookie 读写接口。
typescript
Bun.serve({
  routes: {
    "/profile/:username": async (req) => {
      const { username } = req.params; // 获取路由参数
      const allCookies = req.cookies; // 所有 Cookie（Map）
      const theme = req.cookies.get("theme"); // 读取单个 Cookie

      // 设置 Cookie
      req.cookies.set("session", "abc123", {
        httpOnly: true,
        maxAge: 60 * 60 * 24, // 24 小时
      });

      return new Response(`Profile of ${username}, theme: ${theme}`);
    },
  },
});

三、修改服务器配置

可以在 Bun.serve 的配置对象中直接指定监听的端口和主机名，也可以通过环境变量设置。

typescript
Bun.serve({
  port: 3000, // 默认 3000
  hostname: "0.0.0.0", // 默认 "0.0.0.0"
  routes: {
    /* ... */
  },
});

也可以通过环境变量 $PORT 或 $BUN_PORT 动态指定端口，例如：

bash
PORT=8080 bun run server.ts

四、前端集成（HTML 导入与热重载）

Bun v1.3 开始，支持直接导入 HTML 文件，并利用内置的打包器和开发服务器实现热模块替换（HMR）。

typescript
// 导入 HTML 文件作为文本
import html from "./index.html";

Bun.serve({
  routes: {
    "/": () => new Response(html, { headers: { "Content-Type": "text/html" } }),
  },
});

配合 bun --hot 启动即可获得前端热重载体验，修改 HTML/CSS/JS 会自动刷新页面。

五、总结

特性说明
推荐写法Bun.serve({ routes: {...} })
动态路由"/users/:id" → req.params.id
方法区分为同一路径配置 GET、POST 等对象
通配符"/api/*" 匹配子路径
Cookie 操作req.cookies.get/set/delete
静态文件直接返回 Bun.file(path)
前端集成导入 HTML + bun --hot 实现 HMR

Bun 内置的 HTTP 服务器性能极高，且与 Node.js 的 fetch API 兼容，几乎无需学习成本即可上手。对于 API 开发、静态服务、全栈应用都是一个极佳的选择。

相关文章

Series

bun

3 / 3

生产环境与部署指南