> ## Documentation Index > Fetch the complete documentation index at: https://bun.ll1025.cn/llms.txt > Use this file to discover all available pages before exploring further. # 全栈开发服务器 > 使用 Bun 集成的开发服务器构建全栈应用程序，打包前端资源并处理 API 路由首先，导入 HTML 文件并将其传递给 `Bun.serve()` 的 `routes` 选项。 ```ts title="app.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} import { serve } from "bun"; import dashboard from "./dashboard.html"; import homepage from "./index.html"; const server = serve({ routes: { // ** HTML 导入 ** // 打包 index.html 并路由到 "/"。使用 HTMLRewriter 扫描 // HTML 中的 ` ``` 会被转换成类似这样的内容： ```html title="index.html" icon="file-code" theme={null} 主页

``` ## React 集成要在客户端代码中使用 React，导入 `react-dom/client` 并渲染你的应用。 ```ts title="src/backend.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} import dashboard from "../public/dashboard.html"; import { serve } from "bun"; serve({ routes: { "/": dashboard, }, async fetch(req) { // ... 接口请求 return new Response("hello world"); }, }); ``` ```tsx title="src/frontend.tsx" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} import { createRoot } from "react-dom/client"; import App from "./app"; const container = document.getElementById("root"); const root = createRoot(container!); root.render(); ``` ```html title="public/dashboard.html" icon="file-code" theme={null} 仪表盘

``` ```tsx title="src/app.tsx" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} import { useState } from "react"; export default function App() { const [count, setCount] = useState(0); return (

仪表盘

); } ``` ## 开发模式在本地构建时，通过在 `Bun.serve()` 中设置 `development: true` 来启用开发模式。 ```ts title="src/backend.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} import homepage from "./index.html"; import dashboard from "./dashboard.html"; Bun.serve({ routes: { "/": homepage, "/dashboard": dashboard, }, development: true, fetch(req) { // ... 接口请求 }, }); ``` ### 开发模式特性当 `development` 为 `true` 时，Bun： * 在响应中包含 SourceMap 头，以便开发者工具显示原始源代码 * 禁用压缩 * 在每次请求 `.html` 文件时重新打包资源 * 启用热模块重载（除非设置了 `hmr: false`） ### 高级开发配置要将浏览器的控制台日志回显到终端，在 `Bun.serve()` 的 `development` 对象中传入 `console: true`。 ```ts title="src/backend.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} import homepage from "./index.html"; Bun.serve({ // development 也可以是一个对象。 development: { // 启用热模块重载 hmr: true, // 将浏览器的控制台日志回显到终端 console: true, }, routes: { "/": homepage, }, }); ``` Bun 通过现有的 HMR WebSocket 连接发送日志。 ### 开发 vs 生产 | 特性 | 开发 | 生产 | | -------------- | ------------ | ----- | | **Source map** | ✅ 启用 | ❌ 禁用 | | **压缩** | ❌ 禁用 | ✅ 启用 | | **热重载** | ✅ 启用 | ❌ 禁用 | | **资源打包** | 🔄 每次请求 | 💾 缓存 | | **控制台日志** | 🖥️ 浏览器 → 终端 | ❌ 禁用 | | **错误详情** | 📝 详细 | 🔒 最简 | ## 生产模式热重载和 `development: true` 帮助你在开发中快速迭代，但在生产环境中，你的服务器应该尽可能快且外部依赖尽可能少。 ### 预先打包（推荐）从 Bun v1.2.17 开始，你可以使用 `Bun.build` 或 `bun build` 预先打包你的全栈应用。 ```bash terminal icon="terminal" theme={null} bun build --target=bun --production --outdir=dist ./src/index.ts ``` 当 Bun 的打包器在服务器端代码中看到 HTML 导入时，它会将引用的 JavaScript/TypeScript/TSX/JSX 和 CSS 文件打包到一个清单对象中，`Bun.serve()` 可以使用该对象来提供资源。 ```ts title="src/backend.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} 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 文件 ```ts title="src/backend.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} import { serve } from "bun"; import homepage from "./index.html"; serve({ routes: { "/": homepage, }, // 生产模式 development: false, }); ``` ## API 路由 ### HTTP 方法处理器使用 HTTP 方法处理器定义 API 端点： ```ts title="src/backend.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} 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 参数： ```ts title="src/backend.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} 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); }, }, }); ``` ### 请求处理 ```ts title="src/backend.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} 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: "数据已处理", page: parseInt(page), authenticated: !!auth, }); }, }, }, }); ``` ## 插件 Bun 的打包器插件在打包静态路由时也受支持。要配置 `Bun.serve` 的插件，在 `bunfig.toml` 的 `[serve.static]` 部分添加 `plugins` 数组。 ### TailwindCSS 插件要使用 TailwindCSS，安装 `tailwindcss` 包和 `bun-plugin-tailwind` 插件。 ```bash terminal icon="terminal" theme={null} bun add tailwindcss bun-plugin-tailwind ``` ```toml title="bunfig.toml" icon="settings" theme={null} [serve.static] plugins = ["bun-plugin-tailwind"] ``` 现在你可以在 HTML 和 CSS 文件中使用 TailwindCSS 实用类。在你的项目中的某个地方导入 `tailwindcss`： ```html title="index.html" icon="file-code" theme={null} ``` 或者，你也可以在 CSS 文件中导入 TailwindCSS： ```css title="style.css" icon="file-code" theme={null} @import "tailwindcss"; .custom-class { @apply bg-red-500 text-white; } ``` ```html index.html icon="file-code" theme={null} ``` ### 自定义插件任何导出有效打包器插件对象（一个带有 `name` 和 `setup` 字段的对象）的 JS 文件或模块都可以放在 plugins 数组中： ```toml title="bunfig.toml" icon="settings" theme={null} [serve.static] plugins = ["./my-plugin-implementation.ts"] ``` ```ts title="my-plugin-implementation.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} 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 惰性解析并加载每个插件，并使用它们来打包你的路由。插件位于 `bunfig.toml` 中，这样一旦 `bun build` CLI 支持它们，就可以静态地知道哪些插件正在使用。这些插件在 `Bun.build()` 的 JS API 中有效，但在 CLI 中尚未支持。 ## 内联环境变量 Bun 可以在构建时将前端 JavaScript 和 TypeScript 中的 `process.env.*` 引用替换为其实际值。在你的 `bunfig.toml` 中配置 `env` 选项： ```toml title="bunfig.toml" icon="settings" theme={null} [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 和静态站点](/bundler/html-static#inline-environment-variables)了解构建时配置和示例。 ## 工作原理 Bun 使用 `HTMLRewriter` 扫描 HTML 文件中的 ` ``` * 处理 CSS 导入和 `` 标签 * 合并 CSS 文件 * 重写 URL 和资源路径，在 URL 中包含内容可寻址哈希 ```html title="index.html" icon="file-code" theme={null} ``` * 资源的链接被重写，在 URL 中包含内容可寻址哈希 * CSS 文件中的小资源被内联为 `data:` URL，减少网络传输的 HTTP 请求总数 * 将所有 ` ``` ```tsx title="src/main.tsx" theme={null} import { createRoot } from "react-dom/client"; import { App } from "./App"; const container = document.getElementById("root")!; const root = createRoot(container); root.render(); ``` ```tsx title="src/App.tsx" theme={null} import { useState, useEffect } from "react"; interface User { id: number; name: string; email: string; created_at: string; } export function App() { const [users, setUsers] = useState([]); 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("创建用户失败"); } finally { setLoading(false); } }; const deleteUser = async (id: number) => { if (!confirm("确认删除？")) return; try { const response = await fetch(`/api/users/${id}`, { method: "DELETE", }); if (response.ok) { await fetchUsers(); } } catch (error) { alert("删除用户失败"); } }; useEffect(() => { fetchUsers(); }, []); return (

用户管理

用户列表 ({users.length})

{users.map(user => (

{user.name}
{user.email}

))}

); } ``` ```css title="src/styles.css" icon="file-code" theme={null} * { 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 ``` ### 基于环境的配置 ```ts title="server/config.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} 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 || "*", }, }; ``` ### 错误处理 ```ts title="server/middleware.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} export function errorHandler(error: Error, req: Request) { console.error("服务器错误：", error); if (process.env.NODE_ENV === "production") { return Response.json({ error: "内部服务器错误" }, { status: 500 }); } return Response.json( { error: error.message, stack: error.stack, }, { status: 500 }, ); } ``` ### API 响应辅助函数 ```ts title="server/utils.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} 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 = "未找到") { return error(message, 404); } export function unauthorized(message = "未授权") { return error(message, 401); } ``` ### 类型安全 ```ts title="types/api.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} export interface User { id: number; name: string; email: string; created_at: string; } export interface CreateUserRequest { name: string; email: string; } export interface ApiResponse { data?: T; error?: string; } ``` ## 部署 ### 生产构建 ```bash terminal icon="terminal" theme={null} # 为生产环境构建 bun build --target=bun --production --outdir=dist ./server/index.ts # 运行生产服务器 NODE_ENV=production bun dist/index.js ``` ### Docker 部署 ```dockerfile title="Dockerfile" icon="docker" theme={null} 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 title=".env.production" icon="file-code" theme={null} NODE_ENV=production PORT=3000 DATABASE_URL=postgresql://user:pass@localhost:5432/myapp CORS_ORIGIN=https://myapp.com ``` ## 从其他框架迁移 ### 从 Express + Webpack ```ts title="server.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} // 之前（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 路由 ```ts title="server.ts" icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null} // 之前（Next.js） export default function handler(req, res) { if (req.method === 'GET') { res.json(users); } } // 之后（Bun） "/api/users": { GET() { return Response.json(users); } } ``` ## 限制与未来计划 ### 当前限制 * API 路由的自动发现未实现 * 服务器端渲染（SSR）不是内置功能 ### 计划中的功能 * API 端点的基于文件的路由 * 内置 SSR 支持 * 增强的插件生态系统这是一个进行中的工作。功能和 API 可能会变化。