名称: Bun Runtime 描述: 用于Bun运行时，bunfig.toml，监控/热模式，环境变量，CLI标志和模块解析。版本: 1.0.0

Bun Runtime

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

快速开始

# 运行文件
bun run index.ts
bun index.ts  # 简写

# 使用监控模式运行
bun --watch run index.ts

# 运行package.json脚本
bun run dev

# 使用热重载运行
bun --hot run server.ts

核心CLI标志

标志	用途
`--watch`	在文件更改时重启
`--hot`	热模块替换（保留状态）
`--smol`	减少内存使用（较慢的GC）
`--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    # 正确
bun run dev --watch    # 错误 - 标志传递给脚本

Package.json脚本

# 运行脚本
bun run dev
bun dev  # 简写（如果没有Bun命令冲突）

# 列出可用脚本
bun run

# 使用Bun而不是Node运行
bun run --bun vite

Bun尊重生命周期钩子（preclean、postclean等）。

监控模式 vs 热重载

模式	标志	行为
监控	`--watch`	在更改时完全重启进程
热重载	`--hot`	替换模块，保留状态

# 监控模式 - 完全重启
bun --watch run server.ts

# 热重载 - 保留连接/状态
bun --hot run server.ts

环境变量

Bun自动加载.env文件：

# 自动加载: .env, .env.local, .env.development
bun run index.ts

# 指定环境文件
bun --env-file .env.production run index.ts

# 禁用自动加载
# 在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"]

使用场景：polyfills、全局设置、仪器化。

标准输入执行

# 将代码管道传输给Bun
echo "console.log('Hello')" | bun run -

# 重定向文件
bun run - < script.js

工作区与单体仓库

# 在特定包中运行脚本
bun run --filter 'pkg-*' build

# 在所有工作区运行
bun run --filter '*' test

调试

# 启动调试器
bun --inspect run index.ts

# 等待调试器连接
bun --inspect-wait run index.ts

# 在第一行中断
bun --inspect-brk run index.ts

通过Chrome DevTools或VS Code连接。

常见错误

错误	原因	修复
`Cannot find module`	缺少依赖	运行`bun install`
`Top-level await`	在async外部使用await	包装在async函数中或使用`.mts`
`--watch not working`	标志位置错误	将标志放在`run`之前

何时加载参考文档

加载references/bunfig.md当：

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

加载references/cli-flags.md当：

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

加载references/module-resolution.md当：

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

名称: Bun Runtime 描述: 用于Bun运行时，bunfig.toml，监控/热模式，环境变量，CLI标志和模块解析。 版本: 1.0.0