# macOS / Linux 一键安装脚本（官方推荐）
curl -fsSL https://bun.sh/install | bash
 
# 使用 npm 全局安装
npm install -g bun
 
# 使用 Homebrew 安装（macOS）
brew install oven-sh/bun/bun
 
# 使用 Scoop 安装（Windows）
scoop install bun
 
# 使用 pnpm 全局安装
pnpm add -g bun

bun --version
# 输出: 1.3.14

# bunfig.toml - Bun 全局配置文件
 
[install]
# 配置包管理器行为
registry = "https://registry.npmmirror.com"
# 是否启用全局缓存
globalDir = "~/.bun/install/global"
# 缓存目录
cacheDir = "~/.bun/install/cache"
 
[install.scopes]
# 私有包作用域配置
"@myorg" = "https://npm.myorg.com/"
 
[test]
# 测试运行器配置
coverage = true
coverageReporter = ["text", "lcov"]
# 测试文件匹配模式
# 默认匹配 *.test.ts, *.spec.ts 等
 
[run]
# 脚本运行配置
# 静默模式，不打印 bun run 前缀
silent = true
 
[bundle]
# 打包器配置
outdir = "./dist"
# 输出格式: "esm" | "cjs" | "iife"
format = "esm"
# 目标环境
target = "browser"

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "types": ["bun-types"]
  }
}

bun add -d bun-types

# 初始化项目
mkdir my-bun-app && cd my-bun-app
bun init
 
# 或直接创建 TypeScript 项目
bun init -t ts

// Bun 原生支持 TypeScript，无需编译
const server = Bun.serve({
  port: 3000,
  fetch(request) {
    return new Response("Hello from Bun!")
  },
})
 
console.log(`Server running at http://localhost:${server.port}`)

# 直接运行 TypeScript 文件
bun run index.ts
 
# 或监听文件变化自动重载
bun --watch run index.ts

# 打包为浏览器端 ESM
bun build ./src/index.ts --outdir ./dist --target browser
 
# 打包为单文件
bun build ./src/index.ts --outfile ./dist/bundle.js
 
# 打包为可执行的 Node.js 脚本
bun build ./src/index.ts --target node --outfile ./dist/cli.js

// example.test.ts
import { describe, it, expect, mock } from "bun:test"
 
describe("计算器", () => {
  it("应正确执行加法", () => {
    expect(1 + 1).toBe(2)
  })
 
  it("应支持异步操作", async () => {
    const result = await Promise.resolve(42)
    expect(result).toBe(42)
  })
 
  it("应支持 Mock 函数", () => {
    const fn = mock(() => "original")
    fn.mockReturnValue("mocked")
    expect(fn()).toBe("mocked")
  })
})

# 运行所有测试
bun test
 
# 运行指定文件
bun test src/utils.test.ts
 
# 生成覆盖率报告
bun test --coverage
 
# 过滤测试名称
bun test --filter "计算器"

# 安装所有依赖
bun install       # 等价于 npm install
 
# 添加依赖
bun add express   # 等价于 npm install express
 
# 添加开发依赖
bun add -d typescript
 
# 移除依赖
bun remove express
 
# 更新依赖
bun update
 
# 运行 package.json 脚本
bun run dev       # 等价于 npm run dev
 
# 执行二进制命令
bunx create-next-app  # 等价于 npx create-next-app

import { sql } from "bun"
 
// 创建数据库连接
const db = sql`postgresql://localhost:5432/mydb`
 
// 参数化查询（自动防 SQL 注入）
const users = await db`SELECT * FROM users WHERE age > ${18}`
 
// 插入数据
const result = await db`
  INSERT INTO users (name, email)
  VALUES (${'张三'}, ${'[email protected]'})
  RETURNING *
`
 
// 事务支持
await db.begin(async (trx) => {
  await trx`UPDATE accounts SET balance = balance - 100 WHERE id = 1`
  await trx`UPDATE accounts SET balance = balance + 100 WHERE id = 2`
})

import { redis } from "bun"
 
// 连接 Redis
const client = redis("redis://localhost:6379")
 
// 基本操作
await client.set("key", "value")
const value = await client.get("key")
 
// 支持管道和事务
const pipeline = client.pipeline()
pipeline.set("a", "1")
pipeline.set("b", "2")
pipeline.get("a")
const results = await pipeline.exec()

# 启动前端开发服务器（零配置）
bun dev
 
# 自动检测项目类型，启用对应的 HMR
# React 项目自动启用 Fast Refresh
# Vue/Svelte 项目启用对应的 HMR

# 1. 初始化项目
bun init
# 或从模板创建
bun create next ./my-app
bun create vite ./my-vite-app
 
# 2. 开发模式（自动重载）
bun --watch run src/index.ts
 
# 或使用开发服务器（v1.3+）
bun dev
 
# 3. 类型检查（Bun 不做类型检查，需外部工具）
bunx tsc --noEmit
 
# 4. 运行测试
bun test
 
# 5. 打包构建
bun build ./src/index.ts --outdir ./dist --target browser
 
# 6. 生产运行
bun run ./dist/index.js

// 全局生命周期钩子
import { beforeAll, afterAll, beforeEach, afterEach } from "bun:test"
 
beforeAll(() => {
  // 所有测试前执行一次
  console.log("测试环境初始化")
})
 
afterAll(() => {
  // 所有测试后执行一次
  console.log("测试环境清理")
})
 
// Mock 能力
import { mock, spyOn } from "bun:test"
 
// Mock 模块
mock.module("./config", () => ({
  default: {
    database: "test-db",
    debug: true,
  },
}))
 
// 文件快照测试
it("应生成正确的 HTML", () => {
  const html = renderComponent()
  expect(html).toMatchSnapshot()
})

[test]
coverage = true
coverageReporter = ["text", "lcov", "json"]
coverageDir = "./coverage"
# 预加载模块（如测试环境初始化）
preload = ["./tests/setup.ts"]

# 前端打包（浏览器端）
bun build ./src/main.ts \
  --outdir ./dist \
  --target browser \
  --minify \
  --sourcemap
 
# Node.js 库打包
bun build ./src/index.ts \
  --target node \
  --outdir ./dist \
  --format esm
 
# 编译为单一可执行文件
bun build ./src/cli.ts \
  --compile \
  --outfile my-cli
 
# 多入口打包
bun build ./src/page1.ts ./src/page2.ts \
  --outdir ./dist \
  --target browser

# 方案 1: 直接部署 Bun + 源码
# Dockerfile
FROM oven/bun:1.3 AS base
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --production
COPY . .
EXPOSE 3000
CMD ["bun", "run", "src/index.ts"]
 
# 方案 2: 编译为可执行文件部署
bun build ./src/index.ts --compile --outfile server
# 直接运行编译后的二进制文件
./server
 
# 方案 3: 配合 PM2 进程管理
pm2 start "bun run src/index.ts" --name my-app

# 1. 使用 --production 标志安装依赖
bun install --production
 
# 2. 编译为可执行文件（推荐用于简单服务）
bun build ./src/index.ts --compile --outfile server
 
# 3. 使用 Docker 多阶段构建减小镜像体积
# 构建阶段
FROM oven/bun:1.3 AS build
WORKDIR /app
COPY . .
RUN bun install
RUN bun build ./src/index.ts --compile --outfile server
 
# 运行阶段
FROM debian:bookworm-slim
COPY --from=build /app/server /usr/local/bin/server
EXPOSE 3000
CMD ["server"]
 
# 4. 健康检查
# Bun 内置 HTTP 服务，可实现健康检查端点
Bun.serve({
  port: 3000,
  fetch(req) {
    if (req.url.endsWith("/health")) {
      return new Response(JSON.stringify({ status: "ok" }), {
        headers: { "Content-Type": "application/json" },
      })
    }
    return app.fetch(req)
  },
})

# 1. 安装类型定义
bun add -d bun-types typescript
 
# 2. 配置 tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["bun-types"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true
  }
}
 
# 3. 开发时直接运行 .ts 文件（Bun 负责转译）
bun run src/index.ts
 
# 4. CI 中执行类型检查（Bun 不做类型检查，需外部工具）
bunx tsc --noEmit
# 或使用更快的 tsgo
bunx tsgo --noEmit

// tests/setup.ts - 全局测试初始化
import { beforeAll, afterAll } from "bun:test"
 
// 测试数据库初始化
beforeAll(async () => {
  await Bun.sql`CREATE TABLE IF NOT EXISTS test_users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL
  )`
})
 
afterAll(async () => {
  await Bun.sql`DROP TABLE IF EXISTS test_users`
})
 
// tests/fixtures.ts - 测试数据工厂
export function createUser(overrides?: Partial<User>): User {
  return {
    id: Math.random().toString(36).slice(2),
    name: "测试用户",
    email: "[email protected]",
    ...overrides,
  }
}
 
// tests/utils.test.ts - 使用 fixture
import { describe, it, expect } from "bun:test"
import { createUser } from "./fixtures"
 
describe("UserService", () => {
  it("应正确创建用户", () => {
    const user = createUser({ name: "张三" })
    expect(user.name).toBe("张三")
  })
})

# 1. 使用 --smol 模式降低内存占用
bun --smol run src/index.ts
 
# 2. 使用 --watch 模式进行开发（增量重载）
bun --watch run src/index.ts
 
# 3. 使用 --hot 模式进行热重载
bun --hot run src/index.ts
 
# 4. 利用内置的 Bun.file() 高效读取文件
const file = Bun.file("./data.json")
const data = await file.json()
 
# 5. 使用 Bun.serve() 的高性能 HTTP 服务
Bun.serve({
  port: 3000,
  // 使用路由模式获得更好性能
  routes: {
    "/api/users": handleUsers,
    "/api/posts": handlePosts,
    "/*": handleFallback,
  },
})