bun

Bun

一体化 JavaScript/TypeScript 工具包：运行时、包管理器、测试运行器、打包器。

快速导航

主题	参考资料
包管理器	references/package-manager.md
项目搭建	references/project-scaffolding.md
开发	references/development.md
模块系统	references/module-system.md
TypeScript 和 JSX	references/typescript-jsx.md
配置	references/bunfig.md
HTTP 服务	references/http-server.md
浏览器自动化	references/webview.md
WebSocket	references/websockets.md
文件 I/O	references/file-io.md
SQLite	references/sqlite.md
S3 存储	references/s3.md
Redis	references/redis.md
底层网络	references/networking-low-level.md
Fetch API	references/fetch.md
Shell 脚本	references/shell.md
启动进程	references/spawn.md
Worker	references/workers.md
原生 FFI	references/native-interop.md
C/C++ 编译	references/cc.md
转译器	references/transpiler.md
插件	references/plugins.md
文件系统路由	references/file-system-router.md
环境变量	references/env.md
实用工具	references/utilities.md
Node.js 兼容性	references/nodejs-compat.md

何时使用 Bun

• 无需构建步骤即可运行 TypeScript/JSX
• 使用原生路由的高速 HTTP 服务
• 使用原生输入事件进行无头浏览器自动化
• SQLite 数据库（内嵌，无依赖）
• WebSocket 服务端/客户端
• 兼容 S3 的存储（AWS、R2、MinIO）
• Redis 缓存/发布订阅
• 跨平台 Shell 脚本
• 进程内 cron 调度
• Markdown 解析（v1.3.8+）
• 通过 FFI 调用原生库

核心优势

• 启动速度比 Node.js 快 4 倍
• 原生支持 TypeScript/JSX——无需 tsconfig
• ESM + CommonJS——两者均可无缝运行
• 内置 Web API——fetch、WebSocket 等
• 安装速度比 npm 快 30 倍

快速开始

# Run TypeScript directly
bun run index.ts

# Install packages
bun install

# Run package.json script
bun run dev

# Execute package binary
bunx cowsay "Hello"

# Run tests
bun test

# Build for production
bun build ./index.ts --outdir ./dist

# Bundle analysis for LLMs (v1.3.8+)
bun build ./index.ts --metafile-md --outdir ./dist

关键规则

不要	应使用
http.createServer()	Bun.serve()
fs.readFileSync()	Bun.file().text()
better-sqlite3	bun:sqlite
child_process.exec()	Bun.$ 或 Bun.spawn()
dotenv	内置 .env 支持

版本亮点（1.4.x）

• Rust 重写：首次发布 Rust 移植版本。峰值内存更低（使用 mimalloc 分配器，负载下减少 13-48%）、启动速度约快 2 倍、空闲 CPU 占用降低 5 倍，并且 Node.js 测试套件中通过的测试多出 1,500 多项。
• HTTP/2 和 HTTP/3：Bun.serve() 通过 TLS 上的 ALPN 在同一端口提供 HTTP/1.1 和 HTTP/2 服务（v1.4.1）；HTTP/3 可通过 http3: true 实验性启用。fetch() 可在功能标志启用后使用 HTTP/2/3 客户端。
• 提供静态目录服务：支持 routes: { "/static/*": { dir: "./public" } }，并提供 sendfile、ETag、Range、条件请求和 index.html。
• CLI：使用 bun run --parallel 并发运行脚本；使用 bun audit fix、bun dedupe、bun prune、bun pm diff、bun pm licenses 维护软件包。
• bun test：支持 --parallel、--isolate、--shard=M/N、--timings、--changed（基于差异）、--retry 和 jest.useFakeTimers()。
• bun build：内置 React Compiler（--react-compiler）、优化 barrel 导入、通过 export * as 和动态 import() 实现 tree-shaking、--min-chunk-size 以及模块预加载。
• bun install：支持 --linker=isolated 全局虚拟存储、--offline / --prefer-offline、bun add --catalog、嵌套 overrides 和 selfContained 工作区。
• 新增运行时 API：Bun.Terminal（PTY）、Bun.Archive（tar）、Bun.JSON5/JSONL/JSONC/XML/TOML 解析器、流式 Bun.write(path, response)、WebSocket.pause()/resume()、crypto.argon2，以及 crypto.subtle 中的后量子 ML-DSA/ML-KEM。

版本亮点（1.3.14）

• Bun.Image：内置常见格式的图像解码、转换和编码，无需 npm 依赖或原生插件构建步骤。
• 测试工作流：1.3.13 系列改进了针对变更文件运行测试时的依赖感知筛选，这对依赖局部本地验证的场景很重要。
• 补丁版本运行时改进：1.3.13-1.3.14 在 1.3.12 WebView/cron/Markdown 版本系列的基础上，继续进行兼容性和性能改进。

必备示例

HTTP 服务

Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
    if (url.pathname === "/api/data") {
      return Response.json({ ok: true });
    }
    return new Response("Not Found", { status: 404 });
  },
});

文件操作

// Read
const content = await Bun.file("data.txt").text();

// Write
await Bun.write("output.txt", "Hello World");

// JSON
const config = await Bun.file("config.json").json();

SQLite

import { Database } from "bun:sqlite";

const db = new Database("app.db");
db.run("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");

const insert = db.prepare("INSERT INTO users (name) VALUES (?)");
insert.run("Alice");

const users = db.query("SELECT * FROM users").all();

WebSocket 服务

Bun.serve({
  fetch(req, server) {
    if (server.upgrade(req)) return;
    return new Response("Upgrade failed", { status: 400 });
  },
  websocket: {
    message(ws, message) {
      ws.send(`Echo: ${message}`);
    },
  },
});

Shell 命令

import { $ } from "bun";

// Simple command
const files = await $`ls -la`.text();

// With variables (auto-escaped)
const name = "my file.txt";
await $`cat ${name}`;

// Piping
await $`cat data.csv | grep "pattern" | wc -l`;

S3 存储

import { s3 } from "bun";

// Upload
await s3.file("uploads/doc.pdf").write(data);

// Download
const content = await s3.file("uploads/doc.pdf").text();

// Presigned URL
const url = s3.presign("uploads/doc.pdf", { expiresIn: 3600 });

Redis

import { redis } from "bun";

await redis.set("key", "value");
const value = await redis.get("key");
await redis.expire("key", 3600);

测试

import { expect, test, describe } from "bun:test";

describe("math", () => {
  test("2 + 2 = 4", () => {
    expect(2 + 2).toBe(4);
  });
});

配置（bunfig.toml）

[run]
watch = true

[install]
registry = "https://registry.npmjs.org"

[test]
coverage = true

环境变量

# .env files loaded automatically
DATABASE_URL=postgres://localhost/mydb

// Access
Bun.env.DATABASE_URL;
process.env.DATABASE_URL;
import.meta.env.DATABASE_URL;

链接

• 文档
• 版本发布
• GitHub
• Discord