第一章：Bun 概述

1.1 什么是 Bun？

概念名称	说明	注意事项
Bun 定义	Bun 是一个用 Zig 语言编写的 JavaScript 运行时和包管理器，旨在替代 Node.js，提供更快的启动速度、内置工具链和高度兼容 npm 生态的能力。	Bun 并非仅是包管理器，而是集运行时、测试工具、打包器、服务器于一体的全栈工具。
开发背景	由 Jarred Sumner 于 2022 年首次发布，目标是解决 Node.js 在启动速度、依赖安装效率和现代 Web 开发体验方面的痛点。	Bun 仍处于快速迭代阶段（截至 2026 年），部分 API 可能尚未稳定。
核心目标	极致性能（尤其是冷启动）、零配置 TypeScript/JSX 支持、无缝兼容现有 npm 包、简化开发工作流。	不追求 100% Node.js 兼容，但对主流库（如 Express、React）有良好支持。

1.2 Bun 的核心特性

特性名称	说明	注意事项
极速包安装	使用自研的 bun install 引擎，比 npm/yarn/pnpm 快数倍，支持 .bun 二进制缓存格式。	首次安装后生成 bun.lockb（二进制 lockfile），不可人工编辑。
内置运行时	原生支持 ES 模块、CommonJS、TypeScript、JSX，无需 Babel 或 tsc 预编译。	JSX 默认启用 React 模式；若用于其他框架需配置。
一体化 CLI	单一 bun 命令涵盖 init、add、run、test、serve、build 等功能。	减少项目中工具链依赖（如不再需要 webpack、jest 等）。
原生 fetch 与 WebSocket	全局提供 fetch、WebSocket、Buffer 等 Web 标准 API，无需导入。	Buffer 是全局对象，行为与 Node.js 兼容。
热重载（--watch）	bun run --watch 自动监听文件变更并重启脚本。	适用于开发服务器或长期运行脚本。
原生测试框架	bun test 提供轻量级测试 runner，支持 Jest 风格断言。	不支持所有 Jest 功能（如 transform、coverage 需额外配置）。
零依赖打包	bun build 可将项目打包为单个可执行 JS 文件，支持 tree-shaking。	打包目标目前主要为 Bun 运行时，非浏览器环境。

1.3 Bun 与其他运行时（Node.js、Deno）对比

对比维度	Bun	Node.js	Deno
语言实现	Zig（高性能系统语言）	C++（V8 + libuv）	Rust（Tokio + V8）
启动速度	极快（毫秒级）	较慢（需加载模块系统）	快（但首次运行需下载依赖）
包管理	内置 bun add，兼容 npm registry	依赖 npm/yarn/pnpm	内置，通过 URL 导入（也支持 npm: 前缀）
模块系统	ESM + CommonJS（自动转换）	CommonJS 为主，ESM 实验性	原生 ESM，URL 导入
TypeScript 支持	原生，无需编译	需 tsc 或 ts-node	原生，内置编译器
全局 API	fetch、WebSocket、Buffer 等 Web 标准	需 require('node:xxx') 或 polyfill	fetch、WebSocket 原生，无 Buffer（有 Uint8Array）
安全模型	默认无沙箱（类似 Node.js）	无沙箱	默认安全（需显式授予权限）
生态兼容	高度兼容 npm（>90% 主流包）	完整 npm 生态	通过 npm: 前缀兼容部分 npm 包
适用场景	高性能后端服务、全栈应用、快速原型	企业级后端、成熟生态项目	安全敏感脚本、现代 ESM 项目

注意事项：

• Bun 对 Node.js 内置模块（如 fs、path）提供兼容层，但部分边缘 API 可能缺失。
• Deno 的安全模型更严格，适合脚本分发；Bun 更注重开发体验与性能。
• 在 CI/CD 或 Docker 中使用 Bun 时，建议固定版本以避免兼容性波动。

---

第二章：安装与环境配置

2.1 安装 Bun（各平台）

平台	安装方法	命令示例	注意事项
macOS (Intel/Apple Silicon)	使用官方安装脚本（推荐）	curl -fsSL https://bun.sh/install | bash	自动检测架构，安装到 ~/.bun/bin；需确保 PATH 包含该路径
Linux (x86_64/aarch64)	使用官方安装脚本	curl -fsSL https://bun.sh/install | bash	依赖 glibc ≥ 2.28；Alpine Linux（musl libc）暂不支持
Windows (WSL2)	在 WSL2 的 Ubuntu/Debian 中运行安装脚本	curl -fsSL https://bun.sh/install | bash	仅支持 WSL2，原生 Windows 尚未正式支持（截至 2026 年）
Windows (PowerShell, 实验性)	通过 PowerShell 脚本（社区方案）	iwr https://bun.sh/install.ps1 -useb | iex	非官方支持，稳定性有限，不推荐生产使用
Docker	使用官方镜像	docker run -it oven/bun:latest bun --version	适用于 CI/CD 或隔离环境；镜像基于 Alpine（但 Bun 二进制为 glibc 编译）
Homebrew (macOS/Linux)	通过 brew 安装	brew tap oven-sh/bun && brew install bun	适合已使用 Homebrew 的用户；更新可能略滞后于官方脚本

通用注意事项：

• 安装后需重启终端或手动执行 source ~/.bashrc（或对应 shell 配置文件）以生效 PATH。
• 不建议使用 sudo 安装，Bun 默认安装到用户目录。
• 若安装失败，可尝试设置代理或使用国内镜像（见 2.3 节）。

2.2 验证安装与版本管理

操作名称	操作细节	命令示例	注意事项
验证是否安装成功	检查 bun 命令是否可用并输出版本	bun --version	应返回类似 “1.1.0” 的版本号
查看详细版本信息	显示 Bun、JavaScript 引擎、Zig 编译器等信息	bun --help	可查看所有子命令及版本元数据
升级 Bun	重新运行安装脚本（覆盖安装）	curl -fsSL https://bun.sh/install | bash	自动替换旧版本；保留全局缓存
降级 Bun	手动下载指定版本 tarball 并解压	见官网 releases 页面替换 ~/.bun 目录	需谨慎操作，避免破坏现有项目依赖
多版本管理（实验性）	使用 bun upgrade --version 切换	bun upgrade --version canary	支持 latest、canary、具体版本号（如 1.0.0）
检查兼容性	运行诊断命令	bun -v && bun eval "console.log(Bun.version)"	确保运行时与 CLI 版本一致

注意事项：

• bun upgrade 是官方推荐的升级方式（Bun ≥1.0 后引入）。
• 不支持类似 nvm 的自动多版本切换；如需隔离，建议使用 Docker 或 asdf（社区插件）。
• Canary 版本包含最新特性但可能不稳定，仅用于测试。

2.3 配置全局缓存与镜像源

配置项	配置方法	示例值	注意事项
全局缓存目录	通过环境变量 BUN_INSTALL 设置	export BUN_INSTALL="$HOME/.cache/bun"	默认为 ~/.bun；可自定义以节省主目录空间
npm 镜像源	配置 registry 字段（类似 npm）	bun config set registry https://registry.npmmirror.com	影响 bun add 下载源；支持 .npmrc 文件
使用 .npmrc 文件	在项目根目录或用户目录创建 .npmrc	registry=https://registry.npmmirror.com	Bun 会自动读取该文件中的 registry 配置
清理全局缓存	删除缓存目录或使用命令	rm -rf ~/.bun/install/cache 或 bun pm clear	bun pm clear 为实验性命令，可能随版本变化
禁用二进制锁文件优化	强制使用文本 lockfile（不推荐）	暂无官方支持	bun.lockb 是核心性能优化，不可替换为 package-lock.json
代理配置	通过环境变量设置 HTTP 代理	export HTTP_PROXY=http://proxy.example.com:8080	支持 HTTP_PROXY / HTTPS_PROXY，与 curl 行为一致

注意事项：

• Bun 的缓存机制高度依赖 ~/.bun/install/cache，清理后首次安装会变慢。
• 国内用户强烈建议配置淘宝 NPM 镜像（https://registry.npmmirror.com）以加速依赖下载。
• .npmrc 中的 token、scope 等配置目前部分支持，私有包需测试兼容性。

---

第三章：包管理（bun install / add / remove）

3.1 初始化项目（bun init）

操作名称	操作细节	命令示例	注意事项
交互式初始化	启动向导，配置 package.json 字段	bun init	默认生成最小 package.json；可选 TypeScript、测试框架等
静默初始化（非交互）	跳过提问，使用默认值	bun init -y 或 bun init --yes	适用于自动化脚本；生成字段较少
指定模块类型	设置 type 为 "module" 或 "commonjs"	在交互中选择，或手动编辑 package.json	Bun 默认推荐 "module"（ESM）
生成 tsconfig.json	若选择 TypeScript，自动创建配置文件	bun init → 选择 TypeScript	配置包含 jsx: "preserve"、target: "ESNext" 等
跳过 git 初始化	不自动创建 .gitignore 和 git repo	目前无法通过参数跳过，需手动删除	bun init 会自动运行 git init（若 git 可用）

注意事项：

• bun init 不会安装依赖，仅生成配置文件。
• 生成的 .gitignore 包含 node_modules/、.bun/、*.log 等常见忽略项。
• 若项目已存在 package.json，bun init 会报错，需手动编辑。

3.2 安装依赖（bun add）

方法名称	语法	用途	代码示例	注意事项
安装生产依赖	bun add <pkg>	添加到 dependencies	bun add lodash	自动写入 package.json 并更新 bun.lockb
安装开发依赖	bun add -d 或 bun add --dev	添加到 devDependencies	bun add -d typescript	支持简写 -d
安装可选依赖	bun add -o 或 bun add --optional	添加到 optionalDependencies	bun add -o fsevents	仅在支持平台安装（如 macOS）
安装全局依赖	bun add -g	全局安装 CLI 工具	bun add -g http-server	全局包位于 ~/.bun/bin，需确保 PATH 包含
安装特定版本	bun add <pkg>@<version>	指定版本号或标签	bun add react@18.2.0 或 bun add react@latest	支持语义化版本、tag（如 beta）、Git URL
从 Git 安装	bun add <git-url>	安装 Git 仓库中的包	bun add https://github.com/user/repo.git	支持 #branch、#commit 等后缀
从本地路径安装	bun add file:../my-lib	链接本地包	bun add file:./packages/utils	类似 npm link，但为硬拷贝（非符号链接）
安装并保存精确版本	bun add --exact	锁定具体版本（无 ^）	bun add --exact zod	默认使用 ^ 前缀，--exact 禁用范围匹配

注意事项：

• bun add 会自动运行安装（等效于 bun install），无需额外命令。
• 不支持 --save（默认即保存），也不支持 --no-save。
• 安装速度极快，得益于二进制缓存和并发下载。

3.3 卸载依赖（bun remove）

方法名称	语法	用途	代码示例	注意事项
卸载生产依赖	bun remove <pkg>	从 dependencies 移除	bun remove lodash	同时从 bun.lockb 和 node_modules 删除
卸载开发依赖	bun remove -d	从 devDependencies 移除	bun remove -d typescript	必须指定 -d，否则可能误删生产依赖
卸载全局依赖	bun remove -g	移除全局 CLI 工具	bun remove -g http-server	仅删除 ~/.bun/bin 下的可执行文件
批量卸载	bun remove pkg1 pkg2	一次移除多个包	bun remove express cors body-parser	支持混合生产/开发包（需分别加 -d）

注意事项：

• bun remove 不会自动清理未引用的传递依赖（transitive deps），需手动运行 bun install 优化。
• 若包同时存在于 dev 和 prod，需分别用 bun remove 和 bun remove -d 移除。
• 不支持 --no-save 类选项，卸载即更新 package.json。

3.4 锁定依赖（bun.lockb 文件说明）

概念名称	说明	注意事项
bun.lockb	Bun 使用的二进制格式 lockfile，替代 package-lock.json 或 yarn.lock	文件不可读、不可编辑；由 Bun 自动生成和维护
作用	精确锁定所有依赖（包括嵌套依赖）的版本、完整性哈希、解析地址	确保团队成员和 CI 环境安装完全一致的依赖树
生成时机	首次 bun add 或 bun install 时自动生成	若删除，下次安装会重建
与 npm 兼容性	不兼容 npm/yarn/pnpm 的 lockfile；反之亦然	项目若需多工具协作，建议统一使用 Bun
完整性校验	每个包包含 SHA256 哈希，防止篡改	下载时自动验证，失败则中断安装
版本冲突处理	自动解析依赖图，避免重复或冲突	若出现冲突，Bun 会报错并提示手动干预

注意事项：

• 必须提交 bun.lockb 到 Git，以保证可重现构建。
• 不要尝试手动修改或转换该文件。
• CI 环境中应使用 bun install --frozen-lockfile（若支持）确保锁文件未被更改（截至 2026 年，该选项仍在规划中）。

3.5 使用工作区（Workspaces）

操作名称	操作细节	配置示例	注意事项
启用工作区	在根 package.json 中添加 workspaces 字段	"workspaces": ["packages/*"]	支持 glob 模式（如 packages/**/*）
添加子包	在工作区目录下运行 bun init	cd packages/utils && bun init	子包需有独立 package.json
安装工作区依赖	在根目录运行 bun install	bun install	自动链接所有工作区包（软链接行为）
引用工作区包	在其他子包中直接 add 包名	bun add utils（假设 utils 是子包名）	Bun 自动识别为本地工作区依赖，不从 registry 下载
运行工作区脚本	使用 bun run -w	bun run -w build	-w 表示在所有工作区包中运行
过滤运行脚本	bun run -w --filter	bun run -w --filter "api-*" test	支持通配符过滤包名
发布工作区包	需手动进入子包目录发布	cd packages/utils && npm publish	Bun 暂无内置 publish 命令

注意事项：

• 工作区包之间的依赖关系由 Bun 自动解析，无需 npm link。
• 所有工作区共享根目录的 bun.lockb。
• 不支持 Yarn/NPM 的 nohoist 功能（截至 2026 年）。
• 子包的依赖仍会安装到各自 node_modules（若未提升）。

---

第四章：脚本运行（bun run）

4.1 运行本地脚本

方法名称	语法	用途	代码示例	注意事项
运行 JS/TS 脚本	bun <file>	执行本地 JavaScript/TypeScript 文件	bun index.js 或 bun app.ts	自动识别 .js、.ts、.jsx、.tsx 后缀
运行无后缀脚本	bun <file>	执行无扩展名但含 shebang 的脚本	bun my-script	文件首行需为 #!/usr/bin/env bun
支持 ESM 模块	直接运行	import { foo } from "./lib.js"; console.log(foo());	Bun 默认启用 ESM；无需 --experimental-modules
支持 CommonJS	直接运行	const foo = require("./lib.cjs"); console.log(foo());	自动转换 require 为 ESM 等效逻辑
启用热重载	bun run --watch	监听文件变更并自动重启	bun run --watch server.ts	适用于开发服务器或长期任务
传递脚本参数	bun <file> [args...]	向脚本传入命令行参数	bun script.js --port 3000	参数可通过 process.argv 获取

注意事项：

• 不需要预编译 TypeScript，Bun 内置 transpiler。
• JSX 默认按 React 处理；若用于其他库（如 Preact），需配置 /** @jsx h */。
• --watch 模式会监听脚本及其直接依赖的文件。

4.2 运行 package.json 中的 scripts

方法名称	语法	用途	代码示例	注意事项
运行命名脚本	bun run <script>	执行 package.json 中定义的脚本	bun run dev	等效于 npm run dev，但更快
列出所有脚本	bun run	无参数时列出可用脚本	bun run	显示 scripts 字段中的所有键
并行运行多个脚本	bun run --parallel	同时执行多个脚本（实验性）	bun run --parallel build:js build:css	输出可能交错，适合独立任务
顺序运行脚本	bun run <a> && bun run <b>	串行执行（shell 方式）	bun run clean && bun run build	非 Bun 原生功能，依赖 shell
覆盖脚本命令	bun run <script> -- <args>	向脚本追加参数	bun run test -- --watch	双横线后内容透传给原始命令
运行带空格的脚本名	bun run "my script"	支持带空格的脚本键名	{"my script": "node x.js"} → bun run "my script"	需用引号包裹

注意事项：

• Bun 会优先使用本地 node_modules/.bin 中的 CLI，无需 npx。
• 脚本中可直接使用 bun、tsc 等命令（若已安装）。
• 不支持 npm 的 pre/post 钩子（如 predev），需手动组合。

4.3 直接运行远程/URL 脚本

方法名称	语法	用途	代码示例	注意事项
运行 HTTPS 脚本	bun <url>	直接执行远程 JavaScript 文件	bun https://example.com/script.js	仅支持 HTTPS（不支持 HTTP）
运行 GitHub Gist	bun <url>	执行公开 Gist	bun https://gist.githubusercontent.com/.../raw/.../test.js	URL 需指向原始文件（raw）
缓存远程脚本	自动缓存	首次下载后缓存至 ~/.bun/cache	bun https://cdn.example/lib.js	相同 URL 不重复下载
清除远程缓存	手动删除缓存目录	rm -rf ~/.bun/cache	暂无 bun 命令清理远程脚本缓存，缓存按 URL 哈希存储
传递参数给远程脚本	bun <url> [args]	向远程脚本传参	bun https://ex.com/cli.js --help	参数通过 process.argv 传递

注意事项：

• 远程脚本以严格模式运行，无沙箱，存在安全风险，仅用于可信源。
• 不支持动态 import() 加载远程模块（仅限主入口）。
• 若 URL 返回非 JS 内容（如 HTML），Bun 会报错。

4.4 环境变量与参数传递

操作名称	操作细节	示例	注意事项
设置环境变量（Linux/macOS）	在命令前声明	PORT=3000 bun server.js	仅对当前命令生效
设置环境变量（Windows PowerShell）	$env:PORT="3000"; bun server.js	$env:NODE_ENV="production"; bun start	PowerShell 语法
从 .env 文件加载	Bun 不内置支持	需手动读取或使用第三方库（如 dotenv）	与 Node.js 行为一致；Bun 无自动加载 .env
读取环境变量	process.env.KEY	console.log(process.env.PORT)	全局 process 对象可用
传递命令行参数	通过 process.argv	bun script.js arg1 arg2 → process.argv[2] === "arg1"	argv[0] 为 bun 路径，argv[1] 为脚本路径
使用 minimist 解析参数	需自行引入或使用内置逻辑	const args = process.argv.slice(2)	Bun 未内置参数解析器，推荐使用 yargs 或自定义
透传参数到子进程	在 scripts 中使用 "$@"（shell）	"start": "node server.js $@"	适用于封装脚本

注意事项：

• Bun 不自动加载 .env、.env.local 等文件，需显式处理。
• 环境变量在 Windows CMD 中使用 set VAR=value && bun ...。
• 所有脚本共享同一 V8 实例，环境变量修改会影响全局状态。

---

第五章：Bun 的 JavaScript 运行时

5.1 模块系统支持（ESM、CommonJS）

特性名称	说明	代码示例	注意事项
默认模块系统	Bun 默认使用 ESM（ECMAScript Modules）	// index.js import { foo } from "./lib.js";	文件扩展名必须显式写出（如 .js）
CommonJS 自动转换	require() 和 module.exports 被自动转译为 ESM	// lib.cjs module.exports = { x: 1 }; // index.js const { x } = require("./lib.cjs");	转换在加载时完成，性能开销极低
混合模块导入	ESM 文件可导入 CommonJS 模块	import cjs from "./lib.cjs"; console.log(cjs.x);	CommonJS 模块作为 default 导出对象
动态 import()	支持异步模块加载	const mod = await import("./dynamic.js");	返回 Promise，符合标准
Node.js 内置模块兼容	支持 require("fs")、require("path") 等	import fs from "fs"; 或 const fs = require("fs");	通过 bun:ffi 和内置 polyfill 实现
文件扩展名省略	不支持自动补全扩展名	❌ import "./lib"; → ✅ import "./lib.js";	必须显式指定 .js/.ts/.json 等后缀
JSON 模块导入	直接导入 .json 文件	import pkg from "./package.json"; console.log(pkg.name);	返回解析后的对象，非字符串

注意事项：

• 不支持 --experimental-modules 标志（Bun 原生启用 ESM）。
• __dirname 和 __filename 在 ESM 中不可用；需通过 import.meta.url 构造。
• 循环依赖处理与 Node.js 行为一致，但可能因转译逻辑略有差异。

5.2 内置 API（如 fetch、WebSocket、Buffer）

API 名称	语法	用途	代码示例	注意事项
fetch	fetch(url, options)	发起 HTTP(S) 请求	const res = await fetch("https://api.example.com");	全局可用，无需 import；基于 Web 标准
WebSocket	new WebSocket(url)	创建 WebSocket 客户端	const ws = new WebSocket("wss://echo.websocket.org");	全局构造函数；事件驱动（onopen, onmessage）
Buffer	Buffer.from(str), Buffer.alloc(size)	处理二进制数据	const buf = Buffer.from("hello");	全局对象，API 与 Node.js 完全兼容
setTimeout / setInterval	setTimeout(fn, delay)	定时器	setTimeout(() => console.log("done"), 1000);	全局可用，行为同浏览器/Node.js
process	process.env, process.argv	访问环境与参数	console.log(process.env.NODE_ENV);	提供有限 Node.js process 兼容层
Crypto	全局 crypto 对象	生成随机值、哈希等	const arr = new Uint8Array(16); crypto.getRandomValues(arr);	符合 Web Crypto API 标准
TextEncoder / TextDecoder	new TextEncoder().encode(str)	字符串与 Uint8Array 转换	const bytes = new TextEncoder().encode("hello");	全局可用，Web 标准

注意事项：

• 所有 Web 标准 API（fetch、WebSocket、crypto）均为原生实现，无 polyfill 开销。
• 不支持 Node.js 特有模块如 child_process、cluster（截至 2026 年）。
• Buffer 是全局变量，但建议优先使用 Uint8Array 以保持 Web 兼容性。

5.3 TypeScript 原生支持

特性名称	说明	代码示例	注意事项
无需编译直接运行	.ts 文件可直接由 bun 执行	bun app.ts	自动忽略类型注解，保留运行时代码
tsconfig.json 支持	读取项目根目录 tsconfig.json	{ "compilerOptions": { "target": "ES2022" } }	仅部分字段生效（如 jsx、paths、baseUrl）
类型检查	Bun 不执行类型检查	需配合 tsc --noEmit 单独校验	运行时不报类型错误
路径映射（paths）	支持 compilerOptions.paths	{ "paths": { "@/*": ["src/*"] } } → import "@/utils"	需配合 baseUrl 使用
声明文件（.d.ts）	自动识别同名 .d.ts 文件	utils.ts + utils.d.ts → 类型提示	仅用于编辑器，不影响运行
JSX 支持	默认启用 React JSX 转换	const el = <h1>Hello</h1>;	需安装 react 包，或配置 jsxFactory

注意事项：

• Bun 的 TS 解析基于自研引擎，速度远快于 tsc，但不保证 100% 语法兼容。
• 不支持 emitDecoratorMetadata、experimentalDecorators 等实验性选项。
• 若 tsconfig.json 不存在，Bun 使用默认配置（target: ESNext, module: ESNEXT）。

5.4 JSX 与宏支持

特性名称	说明	代码示例	注意事项
默认 JSX 转换	自动将 JSX 转为 React.createElement	const el = <h1>Hello</h1>; → React.createElement("h1", null, "Hello");	需在作用域中存在 React 变量
自定义 jsxFactory	通过注释或 tsconfig 指定	/** @jsx h */ const el = <div />; → h("div", null);	支持 /* @jsx h */ 和 /* @jsxFrag Empty */
Fragment 支持	<>...</> 语法	const frag = <><span>A</span><span>B</span></>;	默认转为 React.Fragment
宏（Macro）支持	以 ?macro 后缀导入的文件视为编译时宏	import macro from "./build.macro?macro";	宏在构建时执行，返回替换 AST 的函数
宏用途	代码生成、条件编译、静态分析	// build.macro.js export default function() { return { code: "console.log('built at ' + Date.now())" }; }	宏必须是 ESM 模块，导出 default 函数
JSX 与 TSX	.tsx 文件自动启用 JSX	// component.tsx const C = () => <div />;	无需额外配置

注意事项：

• 宏功能为实验性（截至 2026 年），API 可能变更。
• 若未引入 React，JSX 会报 ReferenceError；可改用 Preact 并配置 jsxFactory。
• 不支持 Babel 风格的插件系统；宏是 Bun 特有的编译时扩展机制。

---

第六章：测试（bun test）

6.1 编写测试用例

概念名称	说明	代码示例	注意事项
测试文件命名	Bun 自动识别 *.test.js、*.spec.ts 等	math.test.js、utils.spec.tsx	支持 .js/.ts/.jsx/.tsx 后缀
全局 test 函数	使用 test() 定义单个测试	test("adds 1 + 1", () => { expect(1 + 1).toBe(2); });	无需 import，全局可用
描述性分组	使用 describe() 组织测试套件	describe("Math", () => { test("add", ...) });	支持嵌套 describe
异步测试	直接返回 Promise 或使用 async/await	test("fetches data", async () => { const res = await fetch(...); expect(res.ok).toBe(true); });	无需 done 回调
测试仅运行（skip/only）	使用 .only 或 .skip 修饰	test.only("critical test", ...) 或 test.skip("wip", ...)	适用于调试或临时禁用
测试超时设置	通过 options.timeout 指定	test("slow op", () => {...}, { timeout: 5000 });	默认超时 5000ms

注意事项：

• 不支持 Jest 的 beforeEach/afterAll 等钩子（截至 2026 年）。
• 所有测试默认并行执行；若需串行，需使用 --serial（见 6.3 节）。
• 测试文件可直接导入被测模块，无需额外配置。

6.2 断言与 mock

方法名称	语法	用途	代码示例	注意事项
expect	expect(value)	创建断言对象	expect(result).toBe(42);	全局可用，无需 import
toBe	expect(a).toBe(b)	严格相等（===）	expect(name).toBe("Alice");	适用于原始值
toEqual	expect(a).toEqual(b)	深度相等	expect(obj).toEqual({ id: 1 });	适用于对象/数组
toThrow	expect(fn).toThrow()	验证函数抛出异常	expect(() => badFn()).toThrow();	可传入错误消息或正则
toMatch	expect(str).toMatch(pattern)	字符串匹配正则或子串	expect(msg).toMatch(/error/);	pattern 可为字符串或 RegExp
toBeDefined / toBeNull	expect(x).toBeDefined()	验证非 undefined / null	expect(val).not.toBeNull();	常用于 API 返回值检查
Mock 函数创建	fn = jest.fn() 或 fn = mock()	创建可追踪调用的函数	const cb = mock(); doSomething(cb); expect(cb).toHaveBeenCalled();	mock() 是 Bun 别名，等效于 jest.fn()
Mock 返回值	fn.mockReturnValue(val)	设置 mock 函数返回值	const fn = mock().mockReturnValue(42);	支持链式调用
Mock 实现	fn.mockImplementation(fnImpl)	自定义 mock 行为	fn.mockImplementation((x) => x * 2);	可动态改变逻辑
清除 Mock 状态	mockClear()	重置调用记录	beforeEach(() => { fn.mockClear(); });	需手动管理（无自动 beforeEach）

注意事项：

• Bun 的断言 API 兼容 Jest 风格，但未实现全部 matcher（如 toHaveBeenCalledWith 简化版）。
• mock() 和 jest.fn() 是同一函数，保留 Jest 命名以降低迁移成本。
• 不支持自动 mock（如 Jest 的 automock），需显式创建 mock。

6.3 测试命令与选项

命令/选项	语法	用途	示例	注意事项
运行所有测试	bun test	执行项目中所有匹配的测试文件	bun test	自动递归查找
运行指定文件	bun test <files>	仅运行特定测试文件	bun test math.test.js	支持 glob（如 bun test "src/**/*test.ts"）
匹配测试名称	bun test -t <pattern>	运行名称匹配的测试	bun test -t "addition"	pattern 为正则子串
串行执行	bun test --serial	禁用并行，顺序运行测试	bun test --serial	适用于有状态测试
输出详细日志	bun test --verbose	显示每个测试结果	bun test --verbose	默认仅显示失败项
监听模式	bun test --watch	文件变更时自动重跑测试	bun test --watch	类似 bun run --watch
指定超时	bun test --timeout <ms>	设置全局测试超时	bun test --timeout 10000	覆盖单个测试的 timeout 选项
生成覆盖率（实验性）	bun test --coverage	输出代码覆盖率报告	bun test --coverage	截至 2026 年，功能有限，格式为 lcov
过滤文件	bun test --exclude <glob>	排除特定文件	bun test --exclude "e2e/**"	支持 glob 模式

注意事项：

• bun test 不读取 jest.config.js；所有配置通过命令行参数完成。
• 并行执行是默认行为，可显著提升大型测试套件速度。
• --watch 模式会监听测试文件及其依赖的源文件。

---

第七章：Bun 服务器开发（Bun.serve）

7.1 创建 HTTP 服务器

方法名称	语法	用途	代码示例	注意事项
Bun.serve	Bun.serve(options)	启动高性能 HTTP/HTTPS 服务器	const server = Bun.serve({ port: 3000, fetch(req) { return new Response("OK"); } });	必须提供 fetch 处理函数
options.port	number	指定监听端口	{ port: 8080 }	默认为 3000
options.hostname	string	指定绑定主机	{ hostname: "127.0.0.1" }	默认为 "0.0.0.0"（所有接口）
options.fetch	(req: Request) => Response | Promise<Response>	处理每个请求	fetch(req) { return new Response("Hello"); }	核心处理函数，必须返回 Response
HTTPS 支持	提供 key 和 cert	{ port: 443, key: "...", cert: "..." }	需传入 PEM 格式的私钥和证书字符串，不支持 pfx；需自行读取文件
获取服务器信息	server.port, server.hostname	获取实际绑定地址	console.log("Listening on ${server.hostname}:${server.port}");	若 port 设为 0，系统分配可用端口
关闭服务器	server.stop()	停止监听并关闭连接	setTimeout(() => server.stop(), 5000);	返回 Promise，可 await

注意事项：

• Bun.serve 是低层级 API，不包含路由、中间件等高级功能（需自行实现或使用框架）。
• 所有请求均通过单一 fetch 函数处理，类似 Service Worker。
• 性能极高，单核可处理数万 QPS（基于 Zig 和 epoll/kqueue）。

7.2 路由处理

方法名称	说明	代码示例	注意事项
手动路径匹配	使用 req.url 解析路径	const url = new URL(req.url); if (url.pathname === "/api/users") { ... }	需自行解析查询参数、路径段
方法判断	检查 req.method	if (req.method === "POST") { ... }	支持 GET、POST、PUT、DELETE 等
参数提取	通过路径分割或正则	const id = url.pathname.split("/")[3];	无内置参数路由（如 /user/:id）
JSON 请求体解析	await req.json()	const data = await req.json();	仅可调用一次；后续调用抛错
表单数据解析	await req.formData()	const form = await req.formData();	支持 multipart/form-data
返回 JSON 响应	new Response(JSON.stringify(data), { headers: { "Content-Type": "application/json" } })	return new Response(JSON.stringify({ ok: true }));	需手动设置 Content-Type
错误处理	try/catch 包裹逻辑	try { ... } catch (e) { return new Response("Error", { status: 500 }); }	未捕获异常会导致连接断开

注意事项：

• Bun 不提供内置路由器；复杂路由建议使用 Elysia、Hono 等轻量框架。
• req.json() 会消费请求流，不可重复读取。
• 路径匹配区分大小写（/API ≠ /api）。

7.3 静态文件服务

方法名称	语法	用途	代码示例	注意事项
Bun.file	Bun.file(path)	创建文件引用对象	const file = Bun.file("./public/index.html");	返回 File 对象（Web 标准子类）
返回文件响应	new Response(file)	直接响应文件内容	return new Response(Bun.file("./public/logo.png"));	自动设置 Content-Type 和 Content-Length
检查文件是否存在	await file.exists()	判断文件是否可读	if (await file.exists()) { ... } else { return new Response("Not Found", { status: 404 }); }	exists() 是 Bun 扩展方法
目录列表（需自实现）	fs.readdir + 手动生成 HTML	使用 fs 模块读取目录并构建链接列表	不推荐生产环境暴露目录结构，Bun 无内置目录浏览功能
静态中间件模式	在 fetch 中拦截 /static/*	if (url.pathname.startsWith("/static/")) { const filePath = "." + url.pathname; ... }	需防止路径遍历（如 /static/../../../etc/passwd）
缓存控制	设置 Cache-Control 头	new Response(file, { headers: { "Cache-Control": "max-age=3600" } })	提升 CDN 和浏览器缓存效率

注意事项：

• Bun.file() 不会立即读取文件，仅在 Response 被发送时流式读取。
• 必须校验路径合法性，避免安全漏洞（建议使用 path.resolve + prefix 白名单）。
• 大文件（如视频）可高效流式传输，内存占用低。

7.4 WebSocket 支持

方法名称	语法	用途	代码示例	注意事项
升级 WebSocket	在 fetch 中返回 upgradeToWebSocket	将 HTTP 请求升级为 WebSocket	if (url.pathname === "/ws") { return upgradeToWebSocket(...); }	必须在 fetch 处理函数中调用
upgradeToWebSocket	upgradeToWebSocket(handler, options?)	处理 WebSocket 连接	return upgradeToWebSocket({ open(ws) { ws.send("hello"); }, message(ws, msg) { ws.send(msg); } });	handler 需实现 open/message/close/error
发送消息	ws.send(data)	向客户端推送数据	ws.send("ping"); 或 ws.send(new Uint8Array([1,2,3]));	支持字符串、ArrayBuffer、TypedArray
广播消息	遍历连接池	for (const client of clients) client.send("news");	需自行维护 WebSocket 实例集合，Bun 不提供内置广播机制
关闭连接	ws.close(code?, reason?)	主动断开连接	ws.close(1000, "Going away");	code 遵循 RFC 6455
处理二进制消息	message(ws, msg) 中判断类型	if (msg instanceof ArrayBuffer) { ... }	客户端发送二进制时，msg 为 ArrayBuffer
自定义协议	options.protocol	响应 Sec-WebSocket-Protocol	upgradeToWebSocket(handler, { protocol: "json" })	需与客户端协商一致

注意事项：

• WebSocket 连接建立后，原 HTTP 请求结束，后续通信通过事件驱动。
• 每个 WebSocket 实例是轻量级的，Bun 可轻松支持数万并发连接。
• 不支持 WebSocket 扩展（如 permessage-deflate）。

---

第八章：性能与调试

8.1 启动速度与内存占用

指标/特性	说明	对比参考（Node.js）	注意事项
冷启动时间	执行 bun index.js 的首次启动耗时	通常为 Node.js 的 1/5 ~ 1/10（毫秒级）	得益于 Zig 编写的运行时和快速模块解析
热启动缓存	首次运行后，Bun 缓存字节码至 ~/.bun/cache	Node.js 无内置字节码缓存（需 V8 code cache）	缓存显著加速重复运行
内存占用（空进程）	启动最小脚本的 RSS 内存	~5–10 MB（Node.js 约 20–30 MB）	更适合容器化或资源受限环境
依赖安装内存	bun install 运行时内存峰值	显著低于 npm/yarn（尤其大型项目）	因避免 JavaScript 解析器开销
原生 TypeScript 加载	无需 tsc 预编译，直接运行 .ts	Node.js 需 ts-node（额外解析开销）	减少工具链层级，提升开发体验
模块加载机制	使用自研解析器，非 V8 ScriptCompiler	Node.js 依赖 V8 编译每个模块	Bun 的模块图构建更快

注意事项：

• 性能优势在大型项目（数百依赖）中更为明显。
• 内存数据基于典型 Linux/macOS 环境；Windows (WSL2) 表现接近。
• 若使用大量动态 import() 或 eval()，性能增益可能减弱。

8.2 使用 --watch 模式

操作名称	操作细节	命令示例	注意事项
启用文件监听	添加 --watch 标志运行脚本	bun run --watch server.ts	自动监听脚本及其直接依赖的文件
触发重启条件	任一被依赖的 .js/.ts/.json 文件变更	修改 lib/utils.ts → server.ts 重启	仅监听已加载的模块，非整个目录
忽略特定文件	暂不支持 .watchignore	需通过文件结构隔离	官方尚未提供忽略配置（截至 2026 年）
与测试结合	监听并重跑测试	bun test --watch	测试文件或源文件变更时自动重测
输出清理	重启时清屏并显示 “Restarting…”	控制台自动刷新	便于聚焦最新日志
性能影响	监听使用系统原生 API（inotify / FSEvents）	CPU 占用极低	适用于长期开发会话

注意事项：

• --watch 仅适用于 bun run 和 bun test，不适用于 bun install。
• 不支持监听 node_modules（因 bun.lockb 锁定，通常无需监听）。
• 若脚本崩溃，watch 模式会停止；需手动重启。

8.3 调试 Bun 应用（日志、inspect）

调试方式	语法/操作	用途	示例	注意事项
console.log	console.log(value)	基础日志输出	console.log("User ID:", id);	支持对象、数组、Error 等格式化
Bun.write (stderr)	Bun.write(Bun.stderr, "msg\n")	写入标准错误流	Bun.write(Bun.stderr, JSON.stringify(err) + "\n");	适用于结构化日志
环境变量控制日志	process.env.DEBUG	自定义日志级别开关	if (process.env.DEBUG) console.log("Verbose log");	需自行实现逻辑
Inspector（实验性）	bun run --inspect[=port] script.js	启用 V8 Inspector 兼容协议	bun run --inspect=9229 server.ts	可连接 Chrome DevTools
断点调试	在 DevTools 中设置断点	支持行断点、条件断点	需启用 --inspect	某些 Bun 特有 API（如 Bun.file）可能无法 inspect
堆栈跟踪	自动捕获异常堆栈	throw new Error("Oops");	显示文件、行号、函数名，源码映射（.ts → .js）自动处理
性能分析（实验性）	bun run --cpuprofile out.cpuprofile script.js	生成 CPU 性能剖析文件	需配合外部工具（如 speedscope）查看	功能尚不稳定，文档有限

注意事项：

• --inspect 功能仍在完善中，部分 DevTools 功能（如 Memory Snapshot）可能不可用。
• Bun 不支持 Node.js 的 --trace-warnings、--abort-on-uncaught-exception 等标志。
• 日志输出默认同步，高频率调用可能影响性能；生产环境建议使用异步日志库。

---

第九章：生态与兼容性

9.1 npm 兼容性

兼容特性	说明	支持状态	注意事项
npm registry 访问	可从 https://registry.npmjs.org 下载包	✅ 完全支持	默认源；可替换为私有源或镜像
package.json 字段	读取 dependencies、devDependencies、scripts 等	✅ 基本支持	忽略 publishConfig、engines（部分）等字段
bin 脚本安装	自动链接 CLI 工具到 node_modules/.bin	✅ 支持	bun run 可直接调用，无需 npx
peerDependencies	安装时解析并警告缺失	⚠️ 部分支持	不自动安装，需手动满足
optionalDependencies	按平台选择性安装	✅ 支持	如 fsevents 仅在 macOS 安装
workspaces	支持根 package.json 中的 workspaces 字段	✅ 支持（见 3.5 节）	使用 glob 模式匹配子包目录
.npmrc 配置	读取 registry、token、scope 等	✅ 支持	支持用户目录和项目根目录的 .npmrc
shrinkwrap / lockfile	使用 bun.lockb 替代 package-lock.json	❌ 不兼容	无法与 npm/yarn 共享 lockfile
npm scripts 生命周期	pre/post 脚本钩子（如 prepublish）	❌ 不支持	需手动组合脚本

注意事项：

• Bun 的目标是”足够兼容”，而非 100% 兼容 npm 行为。
• 若项目依赖 yarn/npm 特有功能（如 resolutions、nohoist），需重构。
• 私有 npm 包（需认证）可通过 .npmrc 中的 _authToken 正常工作。

9.2 支持的 Node.js 内置模块

模块名称	支持状态	说明	注意事项
fs	✅ 部分支持	提供 readFile、writeFile、readdir 等 Promise API	不支持 sync 方法（如 readFileSync）；无 watch
path	✅ 完全支持	join、resolve、dirname、extname 等	行为与 Node.js 一致
os	✅ 部分支持	homedir()、platform()、arch()	缺少 loadavg、networkInterfaces 等
events	✅ 完全支持	EventEmitter 类	可用于自定义事件系统
stream	⚠️ 有限支持	基础 Readable/Writable	不推荐用于高性能流处理
http / https	❌ 不支持	请使用 Bun.serve	Node.js http.createServer 无法运行
child_process	❌ 不支持	无 spawn、exec	无法调用外部进程（截至 2026 年）
crypto	✅ 部分支持	createHash、randomBytes	基于 Web Crypto，非完整 Node.js crypto
buffer	✅ 完全支持	Buffer 全局对象	API 与 Node.js 兼容
util	⚠️ 部分支持	inspect、promisify（实验性）	多数工具函数缺失
module	❌ 不支持	无 require.resolve 等	模块解析由 Bun 内部处理

注意事项：

• 所有支持的模块均可通过 import fs from "fs" 或 require("fs") 使用。
• 不支持的模块在导入时会抛出 Cannot find module 错误。
• 建议优先使用 Web 标准 API（如 fetch 代替 http）。

9.3 第三方库兼容情况

库类别	代表库	兼容性	说明	注意事项
Web 框架	Express, Koa, Fastify	⚠️ 部分兼容	可运行，但性能低于原生 Bun.serve	依赖 http 模块，Bun 提供兼容层
现代框架	Elysia, Hono, Polka	✅ 推荐使用	专为 Bun/现代运行时设计	性能最佳，API 简洁
React 生态	React, ReactDOM	✅ 完全支持	JSX、hooks、SSR 均正常	需安装 react 包
构建工具	Vite, esbuild	✅ 支持	可作为开发服务器或构建器	Bun 可替代部分构建步骤
数据库驱动	Prisma, Drizzle ORM	✅ 支持	通过 Bun 的 fetch/fs 运行	Prisma 需启用 --experimental-engine
测试库	Jest, Vitest	⚠️ 有限支持	建议改用 bun test	Jest 配置复杂，Vitest 更兼容
工具库	Lodash, Zod, Day.js	✅ 完全支持	纯 JavaScript，无 Node 特性依赖	可安全使用
文件处理	Sharp, FFmpeg.wasm	❌ 不支持	依赖 native addon 或 child_process	需寻找 WebAssembly 替代方案
WebSocket 库	Socket.IO	⚠️ 部分兼容	可运行，但建议直接用 Bun 内置 WebSocket	性能开销较大

注意事项：

• 兼容性基于纯 ESM/CJS + 无 native addon + 无 child_process 原则。
• 可通过 Bun 官方兼容性仪表盘查询具体包状态。
• 若库使用 process.binding、eval('require') 等动态技巧，可能失败。

---

第十章：高级用法与未来方向

10.1 自定义加载器（Loader）

概念名称	说明	代码示例	注意事项
Loader 作用	控制如何解析特定扩展名的文件（如 .yaml、.png）	将 .yaml 文件转为 JS 对象	类似 Webpack loader，但运行于 Bun 加载时
配置方式	通过 --loader 命令行参数指定	bun run --loader .yaml=./yaml-loader.js app.ts	每个扩展名对应一个 loader 模块
Loader 模块格式	ESM 模块，导出默认函数	// yaml-loader.js export default (code, options) => { return "export default " + JSON.stringify(yaml.parse(code)) + ";" }	接收文件源码字符串，返回 JS 代码字符串
支持的钩子	仅 transform（无 resolve、emit 等）	返回合法 JavaScript 代码即可	不支持异步 loader（截至 2026 年）
内置 Loader	.js/.ts/.jsx/.tsx/.json 已内置	无需配置	自定义 loader 仅用于非标准扩展名
错误处理	抛出异常将终止加载	throw new Error("Invalid YAML");	错误会显示在控制台并中断执行

注意事项：

• Loader 必须是同步函数；不支持 await。
• Loader 仅影响 bun run 和 bun test，不影响 bun install。
• 不支持链式 loader（如 .vue → template + script + style）。

10.2 插件系统（实验性）

特性名称	说明	代码示例	注意事项
插件目的	扩展 Bun 构建或运行时行为（如 CSS 处理、宏替换）	在 bun build 中注入 CSS 提取逻辑	目前仅用于 bun build，非运行时
插件结构	对象含 setup 函数	const cssPlugin = { setup(build) { build.onLoad({ filter: /\.css$/, args => ({ contents: "..." }) }); } };	借鉴 esbuild 插件 API
注册插件	通过 bun build --plugin ./my-plugin.js	bun build --plugin ./css.js entry.ts	插件路径必须为本地文件
onLoad 钩子	拦截文件加载并返回内容	build.onLoad({ filter: /\.txt$/, ({ path }) => ({ contents: "export default " + JSON.stringify(path) }) });	filter 为正则字符串（如 "\.css$"）
onResolve 钩子	自定义模块解析逻辑	build.onResolve({ filter: /^mylib$/, () => ({ path: "./custom-mylib.js" }) });	可重定向导入路径
插件状态	实验性（截至 2026 年）	API 可能变更	不建议用于生产关键路径

注意事项：

• 插件系统主要用于 bun build，对 bun run 无效。
• 插件必须是 ESM 模块，且导出 plugin 对象。
• 不支持热重载插件；修改后需重启构建。

10.3 Bun 的构建工具（bun build）

方法名称	语法	用途	代码示例	注意事项
基本打包	bun build <entry>	将入口文件及其依赖打包为单文件	bun build src/index.ts --outfile dist/app.js	默认输出为 ESM
输出格式	--format [esm | iife | cjs]	指定输出模块格式	bun build --format iife app.ts	iife 适用于浏览器直接引入
最小化	--minify	启用代码压缩	bun build --minify app.ts	包含变量名缩短、死代码消除
目标环境	--target [browser | bun | node]	设置运行时目标	bun build --target browser app.ts	影响 polyfill 和 API 使用
外部依赖	--external <pkg>	排除特定包（不打包）	bun build --external react app.ts	适用于 CDN 引入的库
生成 sourcemap	--sourcemap	输出 .js.map 文件	bun build --sourcemap app.ts	支持 inline 或 external
启用插件	--plugin <file>	加载自定义插件（见 10.2）	bun build --plugin ./css.js app.ts	插件可处理非 JS 资源
打包为可执行文件	--compile	实验性：生成独立二进制	bun build --compile app.ts -o myapp	仅支持 Bun 运行时目标

注意事项：

• bun build 不支持 code splitting（截至 2026 年）。
• 不处理 CSS/图片等资源（需通过插件实现）。
• 构建速度极快（通常 <100ms），适合开发期快速迭代。
• --compile 生成的二进制仍依赖系统 glibc，非完全静态链接。