bun

name	bun
description	Fast, modern JavaScript runtime and toolkit. IMPORTANT: This is Bun, NOT Node.js. Use Bun-specific APIs below. Do NOT use Node.js APIs like require(), process, fs (use Bun.file() instead).

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

Node.js	Bun	Notes
require()	import	默认 ESM
__dirname	import.meta.dir
fs.readFile	Bun.file().text()	更简洁
http.createServer	Bun.serve()	性能更好
bcrypt	Bun.password	内置
dotenv	Bun.env	自动读取
Jest	bun:test	零配置
npm	bun	速度更快

---

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