Bun JS 全棧開發服務器

要開始使用，導入 HTML 文件並將它們傳遞給 Bun.serve() 的 routes 選項。

import { serve } from "bun";
import dashboard from "./dashboard.html";
import homepage from "./index.html";

const server = serve({
  routes: {
    // ** HTML 導入 **
    // 將 index.html 打包並路由到 "/"。這使用 HTMLRewriter 掃描
    // HTML 中的 `<script>` 和 `<link>` 標簽，對它們運行 Bun 的 JavaScript
    // 和 CSS 打包器，轉譯任何 TypeScript、JSX 和 TSX，
    // 使用 Bun 的 CSS 解析器降級 CSS 並提供結果。
    "/": homepage,
    // 將 dashboard.html 打包並路由到 "/dashboard"
    "/dashboard": dashboard,

    // ** API 端點 **（需要 Bun v1.2.3+）
    "/api/users": {
      async GET(req) {
        const users = await sql`SELECT * FROM users`;
        return Response.json(users);
      },
      async POST(req) {
        const { name, email } = await req.json();
        const [user] = await sql`INSERT INTO users (name, email) VALUES (${name}, ${email})`;
        return Response.json(user);
      },
    },
    "/api/users/:id": async req => {
      const { id } = req.params;
      const [user] = await sql`SELECT * FROM users WHERE id = ${id}`;
      return Response.json(user);
    },
  },

  // 啟用開發模式以獲得：
  // - 詳細的錯誤消息
  // - 熱重載（需要 Bun v1.2.3+）
  development: true,
});

console.log(`Listening on ${server.url}`);

bash

bun run app.ts

HTML 路由

HTML 導入作為路由

Web 從 HTML 開始，Bun 的全棧開發服務器也是如此。

要指定前端的入口點，將 HTML 文件導入到您的 JavaScript/TypeScript/TSX/JSX 文件中。

import dashboard from "./dashboard.html";
import homepage from "./index.html";

這些 HTML 文件用作 Bun 開發服務器中的路由，您可以傳遞給 Bun.serve()。

Bun.serve({
  routes: {
    "/": homepage,
    "/dashboard": dashboard,
  },

  fetch(req) {
    // ... api 請求
  },
});

當您向 /dashboard 或 / 發出請求時，Bun 會自動打包 HTML 文件中的 <script> 和 <link> 標簽，將它們暴露為靜態路由，並提供結果。

HTML 處理示例

像這樣的 index.html 文件：

html

<!DOCTYPE html>
<html>
  <head>
    <title>Home</title>
    <link rel="stylesheet" href="./reset.css" />
    <link rel="stylesheet" href="./styles.css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./sentry-and-preloads.ts"></script>
    <script type="module" src="./my-app.tsx"></script>
  </body>
</html>

變成像這樣：

html

<!DOCTYPE html>
<html>
  <head>
    <title>Home</title>
    <link rel="stylesheet" href="/index-[hash].css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/index-[hash].js"></script>
  </body>
</html>

React 集成

要在客戶端代碼中使用 React，導入 react-dom/client 並渲染您的應用。

import dashboard from "../public/dashboard.html";
import { serve } from "bun";

serve({
  routes: {
    "/": dashboard,
  },
  async fetch(req) {
    // ...api 請求
    return new Response("hello world");
  },
});

tsx

import { createRoot } from 'react-dom/client';
import App from './app';

const container = document.getElementById('root');
const root = createRoot(container!);
root.render(<App />);

html

<!DOCTYPE html>
<html>
  <head>
    <title>Dashboard</title>
    <link rel="stylesheet" href="../src/styles.css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="../src/frontend.tsx"></script>
  </body>
</html>

tsx

import { useState } from "react";

export default function App() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h1>Dashboard</h1>
      <button onClick={() => setCount(count + 1)}>Count: {count}</button>
    </div>
  );
}

開發模式

在本地構建時，通過在 Bun.serve() 中設置 development: true 啟用開發模式。

import homepage from "./index.html";
import dashboard from "./dashboard.html";

Bun.serve({
  routes: {
    "/": homepage,
    "/dashboard": dashboard,
  },

  development: true,

  fetch(req) {
    // ... api 請求
  },
});

開發模式功能

當 development 為 true 時，Bun 將：

在響應中包含 SourceMap 頭，以便開發工具可以顯示原始源代碼
禁用壓縮
在每次請求 .html 文件時重新打包資源
啟用熱模塊重載（除非設置了 hmr: false）
將瀏覽器控制台日志回顯到終端

高級開發配置

Bun.serve() 支持將瀏覽器控制台日志回顯到終端。

要啟用此功能，在 Bun.serve() 的 development 對象中傳遞 console: true。

import homepage from "./index.html";

Bun.serve({
  // development 也可以是對象。
  development: {
    // 啟用熱模塊重載
    hmr: true,

    // 將瀏覽器控制台日志回顯到終端
    console: true,
  },

  routes: {
    "/": homepage,
  },
});

當設置 console: true 時，Bun 會將控制台日志從瀏覽器流式傳輸到終端。這重用 HMR 的現有 WebSocket 連接來發送日志。

開發與生產

功能	開發	生產
Source maps	✅ 啟用	❌ 禁用
壓縮	❌ 禁用	✅ 啟用
熱重載	✅ 啟用	❌ 禁用
資源打包	🔄 每次請求	💾 緩存
控制台日志	🖥️ 瀏覽器 → 終端	❌ 禁用
錯誤詳情	📝 詳細	🔒 最小化

生產模式

熱重載和 development: true 幫助您快速迭代，但在生產中，您的服務器應該盡可能快並盡可能少的外部依賴。

提前打包（推薦）

從 Bun v1.2.17 開始，您可以使用 Bun.build 或 bun build 提前打包您的全棧應用程序。

bash

bun build --target=bun --production --outdir=dist ./src/index.ts

當 Bun 的打包器看到來自服務器端代碼的 HTML 導入時，它會將引用的 JavaScript/TypeScript/TSX/JSX 和 CSS 文件打包為清單對象，Bun.serve() 可以使用該對象來提供資源。

import { serve } from "bun";
import index from "./index.html";

serve({
  routes: { "/": index },
});

運行時打包

當添加構建步驟太復雜時，您可以在 Bun.serve() 中設置 development: false。

這將：

啟用打包資源的內存緩存。Bun 將在第一次請求 .html 文件時延遲打包資源，並將結果緩存在內存中直到服務器重啟。
啟用 Cache-Control 頭和 ETag 頭
壓縮 JavaScript/TypeScript/TSX/JSX 文件

import { serve } from "bun";
import homepage from "./index.html";

serve({
  routes: {
    "/": homepage,
  },

  // 生產模式
  development: false,
});

API 路由

HTTP 方法處理程序

使用 HTTP 方法處理程序定義 API 端點：

import { serve } from "bun";

serve({
  routes: {
    "/api/users": {
      async GET(req) {
        // 處理 GET 請求
        const users = await getUsers();
        return Response.json(users);
      },

      async POST(req) {
        // 處理 POST 請求
        const userData = await req.json();
        const user = await createUser(userData);
        return Response.json(user, { status: 201 });
      },

      async PUT(req) {
        // 處理 PUT 請求
        const userData = await req.json();
        const user = await updateUser(userData);
        return Response.json(user);
      },

      async DELETE(req) {
        // 處理 DELETE 請求
        await deleteUser(req.params.id);
        return new Response(null, { status: 204 });
      },
    },
  },
});

動態路由

在路由中使用 URL 參數：

serve({
  routes: {
    // 單個參數
    "/api/users/:id": async req => {
      const { id } = req.params;
      const user = await getUserById(id);
      return Response.json(user);
    },

    // 多個參數
    "/api/users/:userId/posts/:postId": async req => {
      const { userId, postId } = req.params;
      const post = await getPostByUser(userId, postId);
      return Response.json(post);
    },

    // 通配符路由
    "/api/files/*": async req => {
      const filePath = req.params["*"];
      const file = await getFile(filePath);
      return new Response(file);
    },
  },
});

請求處理

serve({
  routes: {
    "/api/data": {
      async POST(req) {
        // 解析 JSON 主體
        const body = await req.json();

        // 訪問頭
        const auth = req.headers.get("Authorization");

        // 訪問 URL 參數
        const { id } = req.params;

        // 訪問查詢參數
        const url = new URL(req.url);
        const page = url.searchParams.get("page") || "1";

        // 返回響應
        return Response.json({
          message: "Data processed",
          page: parseInt(page),
          authenticated: !!auth,
        });
      },
    },
  },
});

插件

打包靜態路由時也支持 Bun 的打包器插件。

要為 Bun.serve 配置插件，在 bunfig.toml 的 [serve.static] 部分中添加 plugins 數組。

TailwindCSS 插件

您可以通過安裝和添加 tailwindcss 包和 bun-plugin-tailwind 插件來使用 TailwindCSS。

bash

bun add tailwindcss bun-plugin-tailwind

[serve.static]
plugins = ["bun-plugin-tailwind"]

這將允許您在 HTML 和 CSS 文件中使用 TailwindCSS 實用程序類。您需要做的就是導入 tailwindcss：

html

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="tailwindcss" />
  </head>
  <!-- 其余的 HTML... -->
</html>

或者，您可以在 CSS 文件中導入 TailwindCSS：

css

@import "tailwindcss";

.custom-class {
  @apply bg-red-500 text-white;
}

html

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <!-- 其余的 HTML... -->
</html>

自定義插件

任何導出有效打包器插件對象（基本上是帶有 name 和 setup 字段的對象）的 JS 文件或模塊都可以放在 plugins 數組中：

[serve.static]
plugins = ["./my-plugin-implementation.ts"]

import type { BunPlugin } from "bun";

const myPlugin: BunPlugin = {
  name: "my-custom-plugin",
  setup(build) {
    // 插件實現
    build.onLoad({ filter: /\.custom$/ }, async args => {
      const text = await Bun.file(args.path).text();
      return {
        contents: `export default ${JSON.stringify(text)};`,
        loader: "js",
      };
    });
  },
};

export default myPlugin;

Bun 將延遲解析和加載每個插件，並使用它們來打包您的路由。

NOTE

這目前在 `bunfig.toml` 中，以便在我們最終將其與 `bun build` CLI 集成時可以靜態知道使用了哪些插件。這些插件在 `Bun.build()` 的 JS API 中有效，但在 CLI 中尚不支持。

內聯環境變量

Bun 可以在構建時用實際值替換前端 JavaScript 和 TypeScript 中的 process.env.* 引用。在 bunfig.toml 中配置 env 選項：

[serve.static]
env = "PUBLIC_*"  # 僅內聯以 PUBLIC_ 開頭的環境變量（推薦）
# env = "inline"  # 內聯所有環境變量
# env = "disable" # 禁用環境變量替換（默認）

注意

這僅適用於字面量 process.env.FOO 引用，不適用於 import.meta.env 或間接訪問如 const env = process.env; env.FOO。

如果環境變量未設置，您可能會在瀏覽器中看到運行時錯誤，如 ReferenceError: process is not defined。

有關構建時配置和示例的更多詳細信息，請參閱 HTML 和靜態站點文檔。

工作原理

Bun 使用 HTMLRewriter 掃描 HTML 文件中的 <script> 和 <link> 標簽，將它們用作 Bun 打包器的入口點，為 JavaScript/TypeScript/TSX/JSX 和 CSS 文件生成優化的打包，並提供結果。

處理流程

1. script 處理

轉譯 <script> 標簽中的 TypeScript、JSX 和 TSX
打包導入的依賴項
生成 sourcemaps 用於調試
當 Bun.serve() 中 development 不為 true 時壓縮

html

<script type="module" src="./counter.tsx"></script>

2. 處理

處理 CSS 導入和 <link> 標簽
連接 CSS 文件
重寫 url 和資源路徑以在 URL 中包含內容尋址哈希

html

<link rel="stylesheet" href="./styles.css" />

3. 和資源處理

重寫資源鏈接以在 URL 中包含內容尋址哈希
CSS 文件中的小資源內聯到 data: URL 中，減少通過網絡發送的 HTTP 請求總數

4. HTML 重寫

將所有 <script> 標簽合並為單個 <script> 標簽，URL 中包含內容尋址哈希
將所有 <link> 標簽合並為單個 <link> 標簽，URL 中包含內容尋址哈希
輸出新的 HTML 文件

5. 服務

打包器的所有輸出文件都作為靜態路由暴露，使用與在 Bun.serve() 中將 Response 對象傳遞給 static 時相同的內部機制。
這與 Bun.build 處理 HTML 文件的方式類似。

完整示例

這是一個完整的全棧應用程序示例：

import { serve } from "bun";
import { Database } from "bun:sqlite";
import homepage from "./public/index.html";
import dashboard from "./public/dashboard.html";

// 初始化數據庫
const db = new Database("app.db");
db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

const server = serve({
  routes: {
    // 前端路由
    "/": homepage,
    "/dashboard": dashboard,

    // API 路由
    "/api/users": {
      async GET() {
        const users = db.query("SELECT * FROM users").all();
        return Response.json(users);
      },

      async POST(req) {
        const { name, email } = await req.json();

        try {
          const result = db.query("INSERT INTO users (name, email) VALUES (?, ?) RETURNING *").get(name, email);

          return Response.json(result, { status: 201 });
        } catch (error) {
          return Response.json({ error: "Email already exists" }, { status: 400 });
        }
      },
    },

    "/api/users/:id": {
      async GET(req) {
        const { id } = req.params;
        const user = db.query("SELECT * FROM users WHERE id = ?").get(id);

        if (!user) {
          return Response.json({ error: "User not found" }, { status: 404 });
        }

        return Response.json(user);
      },

      async DELETE(req) {
        const { id } = req.params;
        const result = db.query("DELETE FROM users WHERE id = ?").run(id);

        if (result.changes === 0) {
          return Response.json({ error: "User not found" }, { status: 404 });
        }

        return new Response(null, { status: 204 });
      },
    },

    // 健康檢查端點
    "/api/health": {
      GET() {
        return Response.json({
          status: "ok",
          timestamp: new Date().toISOString(),
        });
      },
    },
  },

  // 啟用開發模式
  development: {
    hmr: true,
    console: true,
  },

  // 未匹配路由的回退
  fetch(req) {
    return new Response("Not Found", { status: 404 });
  },
});

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

html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Fullstack Bun App</title>
    <link rel="stylesheet" href="../src/styles.css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="../src/main.tsx"></script>
  </body>
</html>

tsx

import { createRoot } from "react-dom/client";
import { App } from "./App";

const container = document.getElementById("root")!;
const root = createRoot(container);
root.render(<App />);

tsx

import { useState, useEffect } from "react";

interface User {
  id: number;
  name: string;
  email: string;
  created_at: string;
}

export function App() {
  const [users, setUsers] = useState<User[]>([]);
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");
  const [loading, setLoading] = useState(false);

  const fetchUsers = async () => {
    const response = await fetch("/api/users");
    const data = await response.json();
    setUsers(data);
  };

  const createUser = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);

    try {
      const response = await fetch("/api/users", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ name, email }),
      });

      if (response.ok) {
        setName("");
        setEmail("");
        await fetchUsers();
      } else {
        const error = await response.json();
        alert(error.error);
      }
    } catch (error) {
      alert("Failed to create user");
    } finally {
      setLoading(false);
    }
  };

  const deleteUser = async (id: number) => {
    if (!confirm("Are you sure?")) return;

    try {
      const response = await fetch(`/api/users/${id}`, {
        method: "DELETE",
      });

      if (response.ok) {
        await fetchUsers();
      }
    } catch (error) {
      alert("Failed to delete user");
    }
  };

  useEffect(() => {
    fetchUsers();
  }, []);

  return (
    <div className="container">
      <h1>User Management</h1>

      <form onSubmit={createUser} className="form">
        <input type="text" placeholder="Name" value={name} onChange={e => setName(e.target.value)} required />
        <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required />
        <button type="submit" disabled={loading}>
          {loading ? "Creating..." : "Create User"}
        </button>
      </form>

      <div className="users">
        <h2>Users ({users.length})</h2>
        {users.map(user => (
          <div key={user.id} className="user-card">
            <div>
              <strong>{user.name}</strong>
              <br />
              <span>{user.email}</span>
            </div>
            <button onClick={() => deleteUser(user.id)} className="delete-btn">
              Delete
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

css

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
  background: #f5f5f5;
  color: #333;
}

.container {
  max-width: 800px;
  margin: 0 auto;
  padding: 2rem;
}

h1 {
  color: #2563eb;
  margin-bottom: 2rem;
}

.form {
  background: white;
  padding: 1.5rem;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  margin-bottom: 2rem;
  display: flex;
  gap: 1rem;
  flex-wrap: wrap;
}

.form input {
  flex: 1;
  min-width: 200px;
  padding: 0.75rem;
  border: 1px solid #ddd;
  border-radius: 4px;
}

.form button {
  padding: 0.75rem 1.5rem;
  background: #2563eb;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.form button:hover {
  background: #1d4ed8;
}

.form button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

.users {
  background: white;
  padding: 1.5rem;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

.user-card {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 1rem;
  border-bottom: 1px solid #eee;
}

.user-card:last-child {
  border-bottom: none;
}

.delete-btn {
  padding: 0.5rem 1rem;
  background: #dc2626;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.delete-btn:hover {
  background: #b91c1c;
}

最佳實踐

項目結構

my-app/
├── src/
│   ├── components/
│   │   ├── Header.tsx
│   │   └── UserList.tsx
│   ├── styles/
│   │   ├── globals.css
│   │   └── components.css
│   ├── utils/
│   │   └── api.ts
│   ├── App.tsx
│   └── main.tsx
├── public/
│   ├── index.html
│   ├── dashboard.html
│   └── favicon.ico
├── server/
│   ├── routes/
│   │   ├── users.ts
│   │   └── auth.ts
│   ├── db/
│   │   └── schema.sql
│   └── index.ts
├── bunfig.toml
└── package.json

基於環境的配置

export const config = {
  development: process.env.NODE_ENV !== "production",
  port: process.env.PORT || 3000,
  database: {
    url: process.env.DATABASE_URL || "./dev.db",
  },
  cors: {
    origin: process.env.CORS_ORIGIN || "*",
  },
};

錯誤處理

export function errorHandler(error: Error, req: Request) {
  console.error("Server error:", error);

  if (process.env.NODE_ENV === "production") {
    return Response.json({ error: "Internal server error" }, { status: 500 });
  }

  return Response.json(
    {
      error: error.message,
      stack: error.stack,
    },
    { status: 500 },
  );
}

API 響應助手

export function json(data: any, status = 200) {
  return Response.json(data, { status });
}

export function error(message: string, status = 400) {
  return Response.json({ error: message }, { status });
}

export function notFound(message = "Not found") {
  return error(message, 404);
}

export function unauthorized(message = "Unauthorized") {
  return error(message, 401);
}

類型安全

export interface User {
  id: number;
  name: string;
  email: string;
  created_at: string;
}

export interface CreateUserRequest {
  name: string;
  email: string;
}

export interface ApiResponse<T> {
  data?: T;
  error?: string;
}

部署

生產構建

bash

# 為生產構建
bun build --target=bun --production --outdir=dist ./server/index.ts

# 運行生產服務器
NODE_ENV=production bun dist/index.js

Docker 部署

dockerfile

FROM oven/bun:1 as base
WORKDIR /usr/src/app

# 安裝依賴項
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

# 復制源代碼
COPY . .

# 構建應用程序
RUN bun build --target=bun --production --outdir=dist ./server/index.ts

# 生產階段
FROM oven/bun:1-slim
WORKDIR /usr/src/app
COPY --from=base /usr/src/app/dist ./
COPY --from=base /usr/src/app/public ./public

EXPOSE 3000
CMD ["bun", "index.js"]

環境變量

ini

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
CORS_ORIGIN=https://myapp.com

從其他框架遷移

從 Express + Webpack 遷移

// 之前（Express + Webpack）
app.use(express.static("dist"));
app.get("/api/users", (req, res) => {
  res.json(users);
});

// 之後（Bun 全棧）
serve({
  routes: {
    "/": homepage, // 替換 express.static
    "/api/users": {
      GET() {
        return Response.json(users);
      },
    },
  },
});

從 Next.js API 路由遷移

// 之前（Next.js）
export default function handler(req, res) {
  if (req.method === 'GET') {
    res.json(users);
  }
}

// 之後（Bun）
"/api/users": {
  GET() { return Response.json(users); }
}

限制和未來計劃

當前限制

bun build CLI 集成尚不適用於全棧應用程序
API 路由的自動發現未實現
服務器端渲染（SSR）未內置

計劃功能

與 bun build CLI 集成
基於文件系統的 API 端點路由
內置 SSR 支持
增強的插件生態系統

NOTE

這是一項正在進行的工作。隨著 Bun 的不斷發展，功能和 API 可能會發生變化。

HTML 路由 ​

HTML 導入作為路由 ​

HTML 處理示例 ​

React 集成 ​

開發模式 ​

開發模式功能 ​

高級開發配置 ​

開發與生產 ​

生產模式 ​

提前打包（推薦） ​

運行時打包 ​

API 路由 ​

HTTP 方法處理程序 ​

動態路由 ​

請求處理 ​

插件 ​

TailwindCSS 插件 ​

自定義插件 ​

內聯環境變量 ​

工作原理 ​

處理流程 ​

1. script 處理 ​

2. 處理 ​

3. 和資源處理 ​

4. HTML 重寫 ​

5. 服務 ​

完整示例 ​

最佳實踐 ​

項目結構 ​

基於環境的配置 ​

錯誤處理 ​

API 響應助手 ​

類型安全 ​

部署 ​

生產構建 ​

Docker 部署 ​

環境變量 ​

從其他框架遷移 ​

從 Express + Webpack 遷移 ​

從 Next.js API 路由遷移 ​

限制和未來計劃 ​

當前限制 ​

計劃功能 ​

HTML 路由

HTML 導入作為路由

HTML 處理示例

React 集成

開發模式

開發模式功能

高級開發配置

開發與生產

生產模式

提前打包（推薦）

運行時打包

API 路由

HTTP 方法處理程序

動態路由

請求處理

插件

TailwindCSS 插件

自定義插件

內聯環境變量

工作原理

處理流程

1. script 處理

2. 處理

3. 和資源處理

4. HTML 重寫

5. 服務

完整示例

最佳實踐

項目結構

基於環境的配置

錯誤處理

API 響應助手

類型安全

部署

生產構建

Docker 部署

環境變量

從其他框架遷移

從 Express + Webpack 遷移

從 Next.js API 路由遷移

限制和未來計劃

當前限制

計劃功能