bun-runtime

Bun 运行时

Bun 是一个基于 JavaScriptCore（Safari 的引擎）构建的快速一体化 JavaScript 运行时。在 Linux 上，它的启动速度比 Node.js 快 4 倍。

快速入门

# Run a file
bun run index.ts
bun index.ts  # shorthand

# Run with watch mode
bun --watch run index.ts

# Run package.json script
bun run dev

# Run with hot reloading
bun --hot run server.ts

核心 CLI 标志

标志	用途
--watch	文件更改时重新启动
--hot	热模块替换（保留状态）
--smol	减少内存使用（垃圾回收速度较慢）
--inspect	启用调试器
--preload	执行前加载模块
--env-file	加载指定的 .env 文件
-e, --eval	执行代码字符串

运行文件

Bun 会即时转译 TypeScript 和 JSX：

bun run index.js
bun run index.ts
bun run index.jsx
bun run index.tsx

重要：将 Bun 标志紧跟在 bun 后面：

bun --watch run dev    # Correct
bun run dev --watch    # Wrong - flag passed to script

package.json 脚本

# Run script
bun run dev
bun dev  # shorthand (if no Bun command conflicts)

# List available scripts
bun run

# Run with Bun instead of Node
bun run --bun vite

Bun 遵循生命周期钩子（preclean、postclean 等）。

监视模式与热重载

模式	标志	行为
监视	--watch	文件更改时完整重启进程
热重载	--hot	替换模块并保留状态

# Watch mode - full restart
bun --watch run server.ts

# Hot reloading - preserves connections/state
bun --hot run server.ts

环境变量

Bun 会自动加载 .env 文件：

# Loads automatically: .env, .env.local, .env.development
bun run index.ts

# Specify env file
bun --env-file .env.production run index.ts

# Disable auto-loading
# In bunfig.toml: env = false

在代码中访问：

const apiKey = process.env.API_KEY;
const bunEnv = Bun.env.NODE_ENV;

可用的全局对象

全局对象	来源	说明
Bun	Bun	主要 API 对象
Buffer	Node.js	二进制数据
process	Node.js	进程信息
fetch	Web	HTTP 请求
Request/Response	Web	HTTP 类型
WebSocket	Web	WebSocket 客户端
crypto	Web	加密功能
console	Web	日志记录
__dirname	Node.js	当前目录
__filename	Node.js	当前文件

预加载脚本

在主脚本运行前加载模块：

bun --preload ./setup.ts run index.ts

或在 bunfig.toml 中配置：

preload = ["./setup.ts"]

适用场景：填充（polyfill）、全局设置、插桩。

从标准输入执行

# Pipe code to Bun
echo "console.log('Hello')" | bun run -

# Redirect file
bun run - < script.js

工作区与单体仓库

# Run script in specific packages
bun run --filter 'pkg-*' build

# Run in all workspaces
bun run --filter '*' test

调试

# Start debugger
bun --inspect run index.ts

# Wait for debugger connection
bun --inspect-wait run index.ts

# Break on first line
bun --inspect-brk run index.ts

通过 Chrome DevTools 或 VS Code 连接。

常见错误

错误	原因	解决方法
Cannot find module	缺少依赖	运行 bun install
Top-level await	在异步上下文之外使用 await	用异步函数包装，或使用 .mts
--watch not working	标志位置错误	将标志放在 run 前面

何时加载参考文档

在以下情况加载 references/bunfig.md：

• 配置 bunfig.toml
• 设置测试配置
• 配置包管理器行为
• 设置 JSX 选项

在以下情况加载 references/cli-flags.md：

• 需要完整的 CLI 标志参考
• 配置高级运行时选项
• 设置调试

在以下情况加载 references/module-resolution.md：

• 排查导入错误
• 配置路径别名
• 了解 Bun 的解析算法