Bun 全指南：从入门到精通

bun run index.tsx       # TS 和 JSX 开箱即用
bun install <pkg>       # 安装包
bun build ./index.tsx   # 打包项目
bun test                # 运行测试
bunx cowsay 'Hello!'    # 执行 npm 包

// Bun 同时支持 Node.js 风格和 Web 标准 API
import { readFileSync } from "fs"; // Node.js API
const response = await fetch("https://api.example.com"); // Web 标准 API

# npm 安装：约 170ms 启动时间
npm install
 
# Bun 安装：约 6ms 启动时间——快 28 倍
bun install

import { expect, test } from "bun:test";
 
test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

bun build ./index.tsx --outdir ./out

# macOS / Linux / WSL
curl -fsSL https://bun.sh/install | bash
 
# Windows
powershell -c "irm bun.sh/install.ps1 | iex"
 
# 使用 npm
npm install -g bun
 
# 使用 Homebrew
brew install oven-sh/bun/bun
 
# 使用 Docker
docker pull oven/bun

bun --version

# 运行文件
bun run index.js
bun run index.ts      # TypeScript 直接运行
bun run index.tsx     # JSX 直接运行
 
# 简写：可以省略 run
bun index.tsx
 
# 运行 package.json 脚本
bun run dev
bun run build
 
# watch 模式
bun --watch run index.tsx

# 安装所有依赖
bun install
 
# 添加包
bun add react
bun add react@19.1.1    # 指定版本
bun add -d typescript    # 开发依赖
 
# 移除包
bun remove react
 
# 全局安装
bun install -g cowsay
 
# CI/CD 模式（冻结锁文件）
bun ci
# 等同于 bun install --frozen-lockfile

{
  "trustedDependencies": ["esbuild", "sharp"]
}

# 提升模式（传统 npm 行为）
bun install --linker hoisted
 
# 隔离模式（类似 pnpm，防止幽灵依赖）
bun install --linker isolated

import { expect, test, describe } from "bun:test";
 
describe("数学运算", () => {
  test("加法", () => {
    expect(1 + 1).toBe(2);
  });
 
  test("异步测试", async () => {
    const data = await fetch("/api/data");
    expect(data.ok).toBe(true);
  });
});

# 运行所有测试
bun test
 
# 运行特定文件的测试
bun test ./test/math.test.ts
 
# 按名称过滤测试
bun test --test-name-pattern "addition"
 
# watch 模式
bun test --watch
 
# 并发执行
bun test --concurrent
 
# 覆盖率报告
bun test --coverage

import { beforeAll, beforeEach, afterEach, afterAll, test } from "bun:test";
 
beforeAll(() => {
  /* 所有测试前执行一次 */
});
beforeEach(() => {
  /* 每个测试前执行 */
});
afterEach(() => {
  /* 每个测试后执行 */
});
afterAll(() => {
  /* 所有测试后执行一次 */
});

import { test, expect, mock } from "bun:test";
 
const random = mock(() => Math.random());
 
test("mock 测试", () => {
  const val = random();
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

# CLI 使用
bun build ./index.tsx --outdir ./out
bun build ./index.tsx --outdir ./out --target browser
bun build ./index.tsx --outdir ./out --watch

// JavaScript API
const result = await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
  target: "browser", // "browser" | "bun" | "node"
});
// result => { success: boolean, outputs: BuildArtifact[], logs: BuildMessage[] }

# 将项目编译为独立可执行文件
bun build --compile ./index.tsx --outfile myapp
./myapp  # 直接运行，无需安装 Bun

const server = Bun.serve({
  port: 3000,
  routes: {
    // 静态路由
    "/api/status": new Response("OK"),
 
    // 动态路由（参数）
    "/users/:id": (req) => {
      return new Response(`Hello User ${req.params.id}!`);
    },
 
    // 按 HTTP 方法分发
    "/api/posts": {
      GET: () => {
        const posts = db.query("SELECT * FROM posts").all();
        return Response.json(posts);
      },
      POST: async (req) => {
        const body = await req.json();
        return Response.json({ created: true, ...body }, { status: 201 });
      },
    },
 
    // 通配符路由
    "/api/*": Response.json({ message: "Not found" }, { status: 404 }),
  },
 
  // 未匹配路由的回退处理
  fetch(req) {
    return new Response("Not Found", { status: 404 });
  },
});
 
console.log(`Server running at ${server.url}`);

// 热重载路由（无需重启服务器）
server.reload({
  routes: {
    "/api/version": () => Response.json({ version: "2.0.0" }),
  },
});
 
// 停止服务器
await server.stop(); // 优雅停止
await server.stop(true); // 强制停止
 
// 获取客户端 IP
const address = server.requestIP(req);

// 读取文件
const text = await Bun.file("./hello.txt").text();
const buffer = await Bun.file("./data.bin").arrayBuffer();
const json = await Bun.file("./config.json").json();
 
// 检查文件是否存在
const exists = await Bun.file("./config.json").exists();
 
// 获取文件信息
const stat = await Bun.file("./data.bin").stat();
console.log(stat.size);
 
// 写入文件
await Bun.write("./output.txt", "Hello, World!");
await Bun.write("./data.bin", new Uint8Array([1, 2, 3]));
 
// 流式写入
const file = Bun.file("./large.txt");
const writable = file.writer();
writable.write("chunk 1\n");
writable.write("chunk 2\n");
writable.end();

import { Database } from "bun:sqlite";
 
const db = new Database(":memory:"); // 或 "mydb.sqlite"
 
// 创建表
db.run("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)");
 
// 插入数据（预处理语句）
const insert = db.prepare("INSERT INTO users (name, email) VALUES ($name, $email)");
insert.run({ $name: "Alice", $email: "alice@example.com" });
insert.run({ $name: "Bob", $email: "bob@example.com" });
 
// 查询数据
const user = db.query("SELECT * FROM users WHERE name = $name").get({ $name: "Alice" });
// => { id: 1, name: "Alice", email: "alice@example.com" }
 
const allUsers = db.query("SELECT * FROM users").all();
// => [{ id: 1, name: "Alice", ... }, { id: 2, name: "Bob", ... }]
 
// 事务
const insertMany = db.transaction((users) => {
  for (const user of users) {
    insert.run(user);
  }
});
 
insertMany([
  { $name: "Charlie", $email: "charlie@example.com" },
  { $name: "Diana", $email: "diana@example.com" },
]);

db.run("PRAGMA journal_mode = WAL;");

class User {
  name: string;
  email: string;
  get displayName() {
    return this.name.toUpperCase();
  }
}
 
const users = db.query("SELECT name, email FROM users").as(User).all();
console.log(users[0].displayName); // "ALICE"

const server = Bun.serve({
  port: 3000,
  fetch(req, server) {
    // 升级 HTTP 请求为 WebSocket
    if (server.upgrade(req)) return;
    return new Response("WebSocket upgrade failed", { status: 500 });
  },
  websocket: {
    open(ws) {
      console.log("客户端已连接");
      ws.subscribe("chat");
    },
    message(ws, message) {
      // 发布消息到所有订阅 "chat" 的客户端
      server.publish("chat", message);
    },
    close(ws) {
      console.log("客户端已断开");
      ws.unsubscribe("chat");
    },
  },
});

// 直接读取，.env 文件自动加载
const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;
 
// 也可以从指定文件加载
// bun --env-file=.env.production run index.ts

import { $ } from "bun";
 
// 运行命令
const result = await $`echo "Hello, World!"`.text();
console.log(result); // "Hello, World!\n"
 
// 管道
const files = await $`ls`.text();
const filtered = await $`grep .ts <<< ${files}`.text();
 
// 带错误处理
try {
  await $`git push`;
} catch (e) {
  console.error("Push failed:", e);
}

// 启动子进程
const proc = Bun.spawn(["echo", "Hello"], {
  stdout: "pipe",
  stderr: "pipe",
});
 
const text = await new Response(proc.stdout).text();
console.log(text); // "Hello\n"
 
const exitCode = await proc.exited;
console.log(`Exit code: ${exitCode}`);

const lib = dlopen("./mylib.so", {
  add: {
    args: ["int", "int"],
    returns: "int",
  },
});
 
console.log(lib.symbols.add(1, 2)); // 3

# 步骤 1：在现有 Node.js 项目中安装 Bun
npm install -g bun
 
# 步骤 2：用 Bun 安装依赖（生成 bun.lock）
bun install
 
# 步骤 3：用 Bun 运行脚本
bun run dev    # 替代 npm run dev
bun test       # 替代 npm test
 
# 步骤 4：如果某个脚本使用 Node.js CLI 工具，用 --bun 标志
bun run --bun vite

// bunfig.toml 中配置插件路径，或直接在代码中使用
const plugin = Bun.plugin({
  name: "my-plugin",
  target: "browser",
  setup(build) {
    build.onLoad({ filter: /\.custom$/ }, (args) => {
      const content = Bun.file(args.path).text();
      return {
        contents: `export default ${JSON.stringify(content)}`,
        loader: "js",
      };
    });
  },
});

# bunfig.toml
 
# 运行时配置
[run]
# 预加载模块
preload = ["./setup.ts"]
 
# 包管理器配置
[install]
# 是否安装可选依赖
optional = true
# 是否安装开发依赖
dev = true
# 安装策略
linker = "hoisted"
# 最小发布年龄（防供应链攻击）
minimumReleaseAge = 259200
 
# 测试配置
[test]
# 覆盖率
coverage = true
# 重试次数
retry = 3
# 超时时间（毫秒）
timeout = 5000

import myReactApp from "./index.html";
 
Bun.serve({
  routes: {
    "/": myReactApp,
    "/api/data": () => Response.json({ message: "Hello" }),
  },
});

const worker = new Worker(new URL("./worker.ts", import.meta.url));
 
worker.postMessage({ type: "process", data: [1, 2, 3] });
 
worker.onmessage = (event) => {
  console.log("Worker 结果:", event.data);
};

bun init
# 选择 "Blank" 模板，然后：
bun add express
bun add -d @types/express

import express from "express";
const app = express();
 
app.get("/", (req, res) => {
  res.json({ message: "Hello from Bun!" });
});
 
app.listen(3000, () => console.log("Running on http://localhost:3000"));

import { Database } from "bun:sqlite";
 
const db = new Database(":memory:");
db.run("CREATE TABLE todos (id INTEGER PRIMARY KEY, text TEXT, done INTEGER DEFAULT 0)");
 
const server = Bun.serve({
  port: 3000,
  routes: {
    "/api/todos": {
      GET: () => {
        const todos = db.query("SELECT * FROM todos").all();
        return Response.json(todos);
      },
      POST: async (req) => {
        const { text } = await req.json();
        db.run("INSERT INTO todos (text) VALUES (?)", [text]);
        return Response.json({ success: true }, { status: 201 });
      },
    },
    "/api/todos/:id": (req) => {
      const todo = db.query("SELECT * FROM todos WHERE id = ?").get(req.params.id);
      if (!todo) return new Response("Not Found", { status: 404 });
      return Response.json(todo);
    },
  },
});

import { test, expect, beforeAll } from "bun:test";
import { Database } from "bun:sqlite";
 
let db: Database;
 
beforeAll(() => {
  db = new Database(":memory:");
  db.run("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
  db.run("INSERT INTO users (name) VALUES ('Alice')");
});
 
test("查询用户", () => {
  const user = db.query("SELECT * FROM users WHERE name = ?").get("Alice");
  expect(user).toBeDefined();
  expect(user.name).toBe("Alice");
});
 
test("所有用户", () => {
  const users = db.query("SELECT * FROM users").all();
  expect(users).toHaveLength(1);
});