Bun

Bun 是面向现代 JavaScript 生态的全新运行时，定位为 Node.js 的替代方案，基于 JavaScriptCore 引擎和 Zig 语言编写。请使用 Bun 特有的 API，不要使用 Node.js 的写法。

Quick Start

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Run a file
bun run index.ts

# Install dependencies
bun install

# Run tests
bun test

Key Features

• Native TypeScript: 直接运行 .ts/.tsx 文件，无需转译
• Built-in Tools: 包管理器、测试、打包工具内置
• Node.js Compatible: 兼容大部分 Node.js 生态
• Web APIs: 原生 fetch, WebSocket, ReadableStream
• Bun.serve(): 高性能 HTTP 服务
• Bun.file(): 简化文件操作
• Bun.password: 原生密码哈希（argon2）
• bun:test: 零配置测试框架

Module Import/Export

重要: Bun 默认使用 ES 模块，兼容 CommonJS，无需额外配置。

// ✅ Bun 写法 - 默认 ES 模块
import fs from 'fs/promises';
export const foo = 'bar';

// ✅ Bun 写法 - 原生支持 TS/JSX（无需转译）
import App from './App.tsx';

// ✅ Bun 兼容 CommonJS（无需额外配置）
const fs = require('fs');
module.exports = { foo: 'bar' };

// ❌ 避免 - Node.js CommonJS 写法
const fs = require('fs');  // 可以用，但推荐上面写法

Global Objects

重要: Bun 有自己的全局对象，优先使用 Bun 特有的写法。

// ✅ Bun 特有 - import.meta.dir/file (所有模块类型通用)
console.log(import.meta.dir);  // 当前目录
console.log(import.meta.file); // 当前文件

// ❌ 避免 - Node.js 写法
// console.log(__dirname);  // 不推荐
// console.log(__filename); // 不推荐

// ✅ Bun 特有 - Bun 全局对象
console.log(Bun.env.NODE_ENV);       // 自动读取 .env
console.log(Bun.version);            // Bun 版本
console.log(Bun.memoryUsage());      // 内存使用

// ✅ Bun 兼容 - process 仍可用
console.log(process.env.NODE_ENV);
console.log(process.pid);

// ✅ Bun 特有 - crypto 全局可用
const bytes = crypto.randomBytes(32);

// ❌ 避免 - Node.js 显式引入
// const crypto = require('crypto'); // 不需要

HTTP Server (最核心差异)

重要: 使用 Bun.serve() 而非 http.createServer()。

// ✅ Bun 写法 - Bun.serve() (简洁高效)
Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response('Hello Bun', {
      headers: { 'Content-Type': 'text/plain' }
    });
  }
});

// ✅ Bun 特有 - 原生 WebSocket 支持
Bun.serve({
  port: 3000,
  fetch(req) {
    if (req.headers.get('upgrade') === 'websocket') {
      const ws = new WebSocket(req);
      ws.on('message', (data) => console.log('Message:', data));
      return ws;
    }
    return new Response('Hello Bun');
  }
});

// ❌ 避免 - Node.js 写法
// const http = require('http');
// const server = http.createServer((req, res) => { ... });

File Operations

重要: 使用 Bun.file() 和 Bun.write() 而非 fs 模块。

// ✅ Bun 写法 - Bun.file() (简洁高效)
// 读取文件
const file = Bun.file('./test.txt');
const text = await file.text();           // 读取为文本
const json = await file.json();            // 读取为 JSON（Bun 特有）
const buffer = = await file.arrayBuffer(); // 读取为 Buffer

// 写入文件
await Bun.write('./test.txt', 'Hello Bun');
await Bun.write('./test.json', { name: 'Bun' }); // 自动序列化

// ✅ Bun 兼容 - 目录操作仍需 fs
import { readdir, mkdir } from 'node:fs/promises';
const files = await readdir(import.meta.dir);
await mkdir('./newDir', { recursive: true });

// ❌ 避免 - Node.js fs 写法（可以但不是最优）
// const fs = require('fs/promises');
// const content = await fs.readFile('./test.txt', 'utf8');

Cryptography

重要: 使用 Bun.password 和 Bun.hash 而非第三方库。

// ✅ Bun 特有 - 密码哈希（无需第三方包）
const hash = await Bun.password.hash('123456'); // 默认 argon2 算法
const isMatch = await Bun.password.verify('123456', hash);

// ✅ Bun 特有 - 哈希计算
const hash1 = Bun.hash('test');        // 默认 wyhash，返回 32 位整数
const hash2 = Bun.hash.sha256('test'); // SHA256，返回十六进制

// ❌ 避免 - Node.js bcrypt 写法
// const bcrypt = require('bcrypt');
// const hash = await bcrypt.hash('123456', 10);

Environment Variables

重要: Bun 自动读取 .env，使用 Bun.env 而非 dotenv。

// ✅ Bun 特有 - 自动读取 .env（无需依赖）
console.log(Bun.env.DB_URL);
console.log(Bun.env.PORT);

// ✅ Bun 兼容 - process.env 仍可用
console.log(process.env.DB_URL);

// ✅ Bun 特有 - TypeScript 类型声明
declare module "bun" {
  interface Env {
    DB_URL: string;
    PORT: string;
  }
}
Bun.env.DB_URL; // 自动提示类型

// ❌ 避免 - Node.js dotenv 写法
// require('dotenv').config(); // 不需要

Package Manager

# ✅ Bun 写法
bun install axios
bun run start
bunx cowsay "Hello"

# ❌ 避免 - npm 写法（可以用但推荐 bun）
# npm install axios
# npm run start

Testing

重要: 使用 bun:test 而非 Jest/Vitest。

// ✅ Bun 写法 - bun:test（零配置，速度快）
import { test, expect } from 'bun:test';

test('1 + 1 = 2', () => {
  expect(1 + 1).toBe(2);
});

// ❌ 避免 - Jest 写法（不需要安装）
// const { test, expect } = require('@jest/globals');

Common Patterns

Running TypeScript

// ✅ Bun 直接运行（无需配置 tsc）
// app.ts
interface User {
  id: number;
  name: string;
}

const user: User = { id: 1, name: 'John' };
console.log(user);

bun run app.ts

SQLite

const db = new Bun.Database('my.db');
const users = db.query('SELECT * FROM users').all();

Migration Checklist

Key Points

1. 使用 Bun API: 优先使用 Bun.serve(), Bun.file(), Bun.write(), Bun.password, Bun.hash
2. 使用 import: 默认 ES 模块，直接 import 而非 require
3. 使用 import.meta.dir: 获取当前目录
4. 使用 Bun.env: 访问环境变量，自动读取 .env
5. 使用 bun:test: 内置测试框架
6. 使用 bun: 包管理和运行脚本

Resources

• Official Documentation
• GitHub Repository
• Bun vs Node.js