路由 - Bun

使用 Bun.serve() 的 routes 属性添加路由（静态路径、参数和通配符），或使用 fetch 方法处理未匹配的请求。 Bun.serve() 的路由器基于 uWebSocket 的树形方法，增加了 SIMD 加速的路由参数解码和 JavaScriptCore 结构缓存，以进一步突破现代硬件的性能极限。

基本设置

server.ts

Bun.serve({
  routes: {
    "/": () => new Response("首页"),
    "/api": () => Response.json({ success: true }),
    "/users": async () => Response.json({ users: [] }),
  },
  fetch() {
    return new Response("未匹配的路由");
  },
});

Bun.serve() 中的路由接收一个 BunRequest（它扩展了 Request）并返回一个 Response 或 Promise<Response>。这使得在发送和接收 HTTP 请求时使用相同的代码变得更加容易。

// 为简洁起见，进行了简化
interface BunRequest<T extends string> extends Request {
  params: Record<T, string>;
  readonly cookies: CookieMap;
}

异步路由

Async/await

在路由处理器中使用 async/await 来返回 Promise<Response>。

import { sql, serve } from "bun";

serve({
  port: 3001,
  routes: {
    "/api/version": async () => {
      const [version] = await sql`SELECT version()`;
      return Response.json(version);
    },
  },
});

Promise

你也可以从路由处理器中返回 Promise<Response>。

import { sql, serve } from "bun";

serve({
  routes: {
    "/api/version": () => {
      return new Promise(resolve => {
        setTimeout(async () => {
          const [version] = await sql`SELECT version()`;
          resolve(Response.json(version));
        }, 100);
      });
    },
  },
});

路由优先级

路由按优先级顺序匹配：

精确路由（/users/all）
参数路由（/users/:id）
通配符路由（/users/*）
全局捕获路由（/*）

Bun.serve({
  routes: {
    // 最具体的优先
    "/api/users/me": () => new Response("当前用户"),
    "/api/users/:id": req => new Response(`用户 ${req.params.id}`),
    "/api/*": () => new Response("API 捕获全部"),
    "/*": () => new Response("全局捕获全部"),
  },
});

类型安全的路由参数

当路径作为字符串字面量传递时，TypeScript 会解析路由参数，因此在访问 request.params 时编辑器会显示自动补全。

index.ts

import type { BunRequest } from "bun";

Bun.serve({
  routes: {
    // 当作为字符串字面量传递时，TypeScript 知道 params 的形状
    "/orgs/:orgId/repos/:repoId": req => {
      const { orgId, repoId } = req.params;
      return Response.json({ orgId, repoId });
    },

    "/orgs/:orgId/repos/:repoId/settings": (
      // 可选：你可以显式地向 BunRequest 传递类型：
      req: BunRequest<"/orgs/:orgId/repos/:repoId/settings">,
    ) => {
      const { orgId, repoId } = req.params;
      return Response.json({ orgId, repoId });
    },
  },
});

Bun 会自动解码百分比编码的路由参数值，包括 Unicode 字符。无效的 Unicode 将被替换为 Unicode 替换字符（\uFFFD）。

静态响应

路由也可以是 Response 对象（无需处理器函数）。Bun.serve() 会对其进行零分配调度优化，适用于健康检查、重定向和固定内容：

Bun.serve({
  routes: {
    // 健康检查
    "/health": new Response("OK"),
    "/ready": new Response("就绪", {
      headers: {
        // 传递自定义头部
        "X-Ready": "1",
      },
    }),

    // 重定向
    "/blog": Response.redirect("https://bun.com/blog"),

    // API 响应
    "/api/config": Response.json({
      version: "1.0.0",
      env: "production",
    }),
  },
});

静态响应在初始化后不会分配额外内存。通常，至少比手动返回 Response 对象有 15% 的性能提升。静态路由响应在服务器对象的生命周期内被缓存。要重新加载静态路由，请调用 server.reload(options)。

文件响应 vs 静态响应

从路由提供文件服务时，行为取决于你是将文件内容缓冲到内存中还是直接提供文件：

Bun.serve({
  routes: {
    // 静态路由 - 启动时内容被缓冲到内存中
    "/logo.png": new Response(await Bun.file("./logo.png").bytes()),

    // 文件路由 - 每次请求时从文件系统读取内容
    "/download.zip": new Response(Bun.file("./download.zip")),
  },
});

静态路由（new Response(await file.bytes())）在启动时将内容缓冲到内存中：

请求期间零文件系统 I/O——内容完全从内存提供
ETag 支持——自动生成和验证 ETag 用于缓存
If-None-Match——当客户端 ETag 匹配时返回 304 Not Modified
没有 404 处理——文件缺失会导致启动时错误，而非运行时 404
内存使用——完整文件内容存储在 RAM 中
最适合：小型静态资源、API 响应、频繁访问的文件

文件路由（new Response(Bun.file(path))）每次请求都从文件系统读取：

每次请求都进行文件系统读取——检查文件是否存在并读取内容
内置 404 处理——如果文件不存在或无法访问，返回 404 Not Found
Last-Modified 支持——使用文件修改时间用于 If-Modified-Since 头部
If-Modified-Since——自客户端缓存版本以来文件未更改时返回 304 Not Modified
范围请求支持——自动处理带有 Content-Range 头部的部分内容请求
流式传输——使用支持背压的缓冲读取器，内存效率高
内存高效——传输期间仅缓冲小块数据，而非整个文件
最适合：大文件、动态内容、用户上传、频繁变化的文件

流式传输文件

要流式传输文件，返回一个以 BunFile 对象作为主体的 Response 对象。

Bun.serve({
  fetch(req) {
    return new Response(Bun.file("./hello.txt"));
  },
});

⚡️ 速度 — Bun 在可能的情况下自动使用 sendfile(2) 系统调用，在内核中实现零拷贝文件传输——这是发送文件的最快方式。

要发送文件的一部分，使用 Bun.file 对象上的 slice(start, end) 方法。Bun 会自动在 Response 对象上设置 Content-Range 和 Content-Length 头部。

Bun.serve({
  fetch(req) {
    // 解析 `Range` 头部
    const [start = 0, end = Infinity] = req.headers
      .get("Range") // Range: bytes=0-100
      .split("=") // ["Range: bytes", "0-100"]
      .at(-1) // "0-100"
      .split("-") // ["0", "100"]
      .map(Number); // [0, 100]

    // 返回文件的一个切片
    const bigFile = Bun.file("./big-video.mp4");
    return new Response(bigFile.slice(start, end));
  },
});

`fetch` 请求处理器

fetch 处理器对没有匹配到路由的传入请求运行。它接收一个 Request 对象，并返回一个 Response 或 Promise<Response>。

Bun.serve({
  fetch(req) {
    const url = new URL(req.url);
    if (url.pathname === "/") return new Response("首页!");
    if (url.pathname === "/blog") return new Response("博客!");
    return new Response("404!");
  },
});

fetch 处理器支持 async/await：

import { sleep, serve } from "bun";

serve({
  async fetch(req) {
    const start = performance.now();
    await sleep(10);
    const end = performance.now();
    return new Response(`休眠了 ${end - start}ms`);
  },
});

也支持基于 Promise 的响应：

Bun.serve({
  fetch(req) {
    // 将请求转发到另一台服务器。
    return fetch("https://example.com");
  },
});

fetch 处理器还将 Server 对象作为其第二个参数接收。

// `server` 作为 `fetch` 的第二个参数传入。
const server = Bun.serve({
  fetch(req, server) {
    const ip = server.requestIP(req);
    return new Response(`你的 IP 是 ${ip.address}`);
  },
});

开始入门

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

互操作与工具

实用工具

标准与兼容性

贡献指南

路由

基本设置

异步路由

Async/await

Promise

路由优先级

类型安全的路由参数

静态响应

文件响应 vs 静态响应

流式传输文件

`fetch` 请求处理器

​基本设置

​异步路由

​Async/await

​Promise

​路由优先级

​类型安全的路由参数

​静态响应

​文件响应 vs 静态响应

​流式传输文件

​fetch 请求处理器

基本设置

异步路由

Async/await

Promise

路由优先级

类型安全的路由参数

静态响应

文件响应 vs 静态响应

流式传输文件

`fetch` 请求处理器