BunHTTP服务器构建 BunHTTPServer

---

名称: Bun HTTP 服务器 描述: 当使用Bun.serve构建HTTP服务器、处理请求/响应、实现路由、创建REST API或配置fetch处理器时使用。 版本: 1.0.0

Bun HTTP 服务器

Bun通过Bun.serve()内置了一个高性能的HTTP服务器。

快速开始

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

console.log(`服务器运行在 http://localhost:${server.port}`);

请求处理

Bun.serve({
  fetch(req) {
    const url = new URL(req.url);

    // 方法
    console.log(req.method); // GET, POST等

    // 路径
    console.log(url.pathname); // /api/users

    // 查询参数
    console.log(url.searchParams.get("id")); // ?id=123

    // 头部
    console.log(req.headers.get("Content-Type"));

    return new Response("OK");
  },
});

请求体解析

Bun.serve({
  async fetch(req) {
    // JSON
    const json = await req.json();

    // 表单数据
    const form = await req.formData();

    // 文本
    const text = await req.text();

    // ArrayBuffer
    const buffer = await req.arrayBuffer();

    // Blob
    const blob = await req.blob();

    return new Response("已接收");
  },
});

响应类型

Bun.serve({
  fetch(req) {
    const url = new URL(req.url);

    switch (url.pathname) {
      case "/json":
        return Response.json({ message: "Hello" });

      case "/html":
        return new Response("<h1>Hello</h1>", {
          headers: { "Content-Type": "text/html" },
        });

      case "/redirect":
        return Response.redirect("/new-location", 302);

      case "/file":
        return new Response(Bun.file("./image.png"));

      case "/stream":
        return new Response(
          new ReadableStream({
            start(controller) {
              controller.enqueue("chunk1");
              controller.enqueue("chunk2");
              controller.close();
            },
          })
        );

      default:
        return new Response("未找到", { status: 404 });
    }
  },
});

简单路由

Bun.serve({
  fetch(req) {
    const url = new URL(req.url);
    const path = url.pathname;
    const method = req.method;

    // 静态路由
    if (method === "GET" && path === "/") {
      return new Response("首页");
    }

    if (method === "GET" && path === "/api/users") {
      return Response.json([{ id: 1, name: "Alice" }]);
    }

    // 动态路由
    const userMatch = path.match(/^\/api\/users\/(\d+)$/);
    if (method === "GET" && userMatch) {
      const userId = userMatch[1];
      return Response.json({ id: userId });
    }

    // 404
    return new Response("未找到", { status: 404 });
  },
});

错误处理

Bun.serve({
  fetch(req) {
    try {
      // 处理请求
      throw new Error("出错了");
    } catch (error) {
      return new Response(
        JSON.stringify({ error: error.message }),
        {
          status: 500,
          headers: { "Content-Type": "application/json" }
        }
      );
    }
  },
  error(error) {
    // 全局错误处理器
    return new Response(`错误: ${error.message}`, { status: 500 });
  },
});

服务器选项

const server = Bun.serve({
  port: 3000,           // 默认: 3000
  hostname: "0.0.0.0",  // 默认: "0.0.0.0"

  development: true,    // 在浏览器中显示友好的错误信息

  // TLS/HTTPS
  tls: {
    key: Bun.file("./key.pem"),
    cert: Bun.file("./cert.pem"),
  },

  // Unix套接字
  unix: "/tmp/my-socket.sock",

  // 最大请求体大小（默认128MB）
  maxRequestBodySize: 1024 * 1024 * 10, // 10MB

  fetch(req) {
    return new Response("OK");
  },
});

服务器方法

const server = Bun.serve({ ... });

// 服务器信息
console.log(server.port);        // 3000
console.log(server.hostname);    // "0.0.0.0"
console.log(server.url);         // URL对象

// 停止服务器
server.stop();

// 重新加载新配置
server.reload({
  fetch(req) {
    return new Response("已更新!");
  },
});

// 待处理请求计数
console.log(server.pendingRequests);

静态文件服务

Bun.serve({
  fetch(req) {
    const url = new URL(req.url);

    // 从public/目录提供静态文件
    if (url.pathname.startsWith("/static/")) {
      const filePath = `./public${url.pathname.replace("/static", "")}`;
      const file = Bun.file(filePath);

      if (await file.exists()) {
        return new Response(file);
      }
      return new Response("未找到", { status: 404 });
    }

    return new Response("API");
  },
});

CORS

function corsHeaders() {
  return {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
    "Access-Control-Allow-Headers": "Content-Type, Authorization",
  };
}

Bun.serve({
  fetch(req) {
    // 处理预检请求
    if (req.method === "OPTIONS") {
      return new Response(null, { headers: corsHeaders() });
    }

    // 添加CORS头部到响应
    return new Response("OK", { headers: corsHeaders() });
  },
});

常见错误

错误	原因	修复方法
EADDRINUSE	端口被占用	使用不同端口或终止进程
无法读取请求体	请求体已被消费	仅读取请求体一次
CORS错误	缺少头部	添加CORS头部
413 负载过大	请求体超过限制	增加maxRequestBodySize

何时加载参考

加载 references/tls-config.md 当：

• HTTPS/TLS设置
• 证书配置
• mTLS身份验证

加载 references/streaming.md 当：

• 服务器发送事件
• 流式响应
• 分块传输编码