Bun 新手使用指南：从安装到精通的全栈开发之旅

适用版本：Bun v1.3.x（截至 2026 年 5 月稳定版）
目标读者：具备 JS/TS 基础，熟悉 Node.js 生态
阅读时间：30–40 分钟（含实操）

一、为什么关注 Bun？

Bun 是一个 All-in-One JavaScript/TypeScript 工具链，集成：

✅ 运行时
✅ 包管理器
✅ 打包器
✅ 测试运行器

核心优势

指标	官方基准对比
包安装速度	~ npm 的 7 倍
HTTP 吞吐量	~ Node.js 的 3 倍
测试执行速度	~ Jest 的 13 倍

技术基础

使用 Zig 编写
基于 JavaScriptCore（非 V8）
单一可执行文件
零配置 TypeScript 支持

内置能力（无需第三方包）

TypeScript 转译
.env 自动加载
SQLite
密码哈希（argon2id/bcrypt）
打包工具

✅ 优势：

node_modules 体积减少 40%+
降低供应链风险
更快 CI/CD

二、环境准备与安装

2.1 系统支持

系统	要求	成熟度
macOS	13+	⭐⭐⭐⭐⭐
Linux	内核 ≥ 5.1	⭐⭐⭐⭐⭐
Windows	Win10+	⭐⭐⭐

CPU 要求

标准版：需要 AVX2（2013年后 CPU）
Baseline：兼容老 CPU

检查 AVX2：

grep -q "avx2" /proc/cpuinfo && echo "支持 AVX2"

2.2 安装方式

✅ 官方脚本（推荐）

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

安装位置：

~/.bun/bin/bun

Windows

powershell -c "irm bun.sh/install.ps1 | iex"

npm 安装

npm install -g bun

Proto 版本管理（团队推荐）

proto install bun

2.3 升级

bun upgrade  
bun upgrade --version 1.3.13  
bun upgrade --canary

团队项目建议锁定版本。

三、项目初始化与包管理

3.1 初始化

bun init  
bun init -y

3.2 常用命令

bun install  
bun add hono  
bun remove pkg  
bun update  
bun outdated  
bun why express

3.3 锁文件

v1.2+ 默认 bun.lock（文本格式）
支持切换为 binary

3.4 隔离安装

bun install --linker=isolated

✅ 杜绝幽灵依赖

3.5 环境变量

自动加载：

.env  
.env.local  
.env.production

无需 dotenv。

四、运行时核心能力

4.1 运行代码

bun index.ts  
bun --hot server.ts  
bun --watch script.ts

--watch vs --hot

模式	行为
watch	整体重启
hot	模块级热替换

4.2 TypeScript 原生支持

自动转译
不做类型检查

4.3 HTTP 服务器（Bun.serve）

const server = Bun.serve({  
  port: 3000,  
  fetch(req) {  
    return new Response("Hello Bun");  
  }  
});

支持：

Web 标准 Request/Response
SSE
WebSocket

4.4 文件系统

await Bun.write("file.txt", "hello");  
const file = Bun.file("data.json");  
await file.json();

✅ 惰性加载
✅ 流式读取

4.5 密码学

await Bun.password.hash(password, {  
  algorithm: "argon2id",  
  cost: 8  
});

无需 bcrypt 包。

4.6 子进程

const proc = Bun.spawn(["ls"], { stdout: "pipe" });

返回 Web Stream。

4.7 SQLite（内置）

import { Database } from "bun:sqlite";  
const db = new Database("mydb.sqlite");

同步 API
支持事务
建议搭配 Drizzle ORM

五、测试：bun:test

5.1 基本用法

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

5.2 运行

bun test  
bun test --watch  
bun test --concurrent

✅ Jest 兼容
✅ 极快执行速度

六、打包与编译

6.1 构建

bun build src/index.ts --outdir dist

6.2 编译为独立可执行文件

bun build server.ts --compile --outfile my-app

✅ 无需安装 Bun 即可运行

七、全栈开发

7.1 Hono

import { Hono } from "hono";

轻量跨运行时。

7.2 Elysia

专为 Bun 优化，性能极致。

八、部署方案

方案	难度	适用
Docker	⭐⭐	通用
Vercel	⭐	Serverless
systemd	⭐⭐⭐	裸机
--compile	⭐	CLI 分发

九、Monorepo

{  
  "workspaces": ["packages/*", "apps/*"]  
}

支持：

bun --filter "apps/*" run test

十、迁移策略

推荐渐进式：

1️⃣ bun install
2️⃣ bun test
3️⃣ bun run
4️⃣ 使用 Bun 专有 API

十一、生产 Checklist

✅ 锁定 Bun 版本
✅ frozen-lockfile
✅ CI 中加入 tsc
✅ systemd 或 Docker restart
✅ 健康检查
✅ 日志收集
✅ Secret 管理

十二、总结

适合场景

✅ 新项目
✅ Serverless
✅ CLI 工具
✅ AI Agent 基础设施
✅ 内部工具

谨慎场景

❗ 依赖 C++ 原生插件
❗ 企业级超长生命周期系统
❗ Windows 生产环境

最终评价

Bun 不是简单的 Node.js 替代品，而是 JavaScript 生态的 新物种：

JavaScriptCore 而非 V8
Zig 而非 C++
All-in-One 而非工具拼装

它带来的改变不仅是“更快”，而是 开发体验的质变。

如果你是个人开发者或中小团队——

👉 现在就可以开始使用 Bun。

从 bun init 到 --compile：Bun v1.3 全栈开发与部署实战手册