Bun 运行时使用指南：快速启动、CLI 标志、热重载与调试教程

Bun Runtime by secondsky/claude-skills

93 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/secondsky/claude-skills --skill 'Bun Runtime'

Node.js 开发性能优化

🇨🇳中文介绍

Bun 运行时

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`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

监听模式 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`	在异步函数外使用 await	包装在异步函数中或使用 `.mts`
`--watch not working`	标志位置错误	将标志放在 `run` 之前

何时加载参考文档

加载 references/bunfig.md 当：

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

加载 references/cli-flags.md 当：

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

加载 references/module-resolution.md 当：

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

🇺🇸English

Bun Runtime

Bun is a fast all-in-one JavaScript runtime built on JavaScriptCore (Safari's engine). It provides 4x faster startup than Node.js on Linux.

Quick Start

# 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

Core CLI Flags

Flag	Purpose
`--watch`	Restart on file changes
`--hot`	Hot module replacement (preserves state)
`--smol`	Reduce memory usage (slower GC)
`--inspect`	Enable debugger
`--preload`	Load modules before execution
`--env-file`	Load specific .env file
`-e, --eval`	Evaluate code string

Running Files

Bun transpiles TypeScript and JSX on-the-fly:

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

Important : Put Bun flags immediately after bun:

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

Package.json Scripts

# 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 respects lifecycle hooks (preclean, postclean, etc.).

Watch Mode vs Hot Reloading

Mode	Flag	Behavior
Watch	`--watch`	Full process restart on changes
Hot	`--hot`	Replace modules, preserve state

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

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

Environment Variables

Bun automatically loads .env files:

# 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

Access in code:

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

Globals Available

Global	Source	Notes
`Bun`	Bun	Main API object
`Buffer`	Node.js	Binary data
`process`	Node.js	Process info
`fetch`	Web	HTTP requests
`Request/Response`	Web	HTTP types

Preload Scripts

Load modules before your main script:

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

Or in bunfig.toml:

preload = ["./setup.ts"]

Use cases: polyfills, global setup, instrumentation.

Stdin Execution

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

# Redirect file
bun run - < script.js

Workspaces & Monorepos

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

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

Debugging

# 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

Connect via Chrome DevTools or VS Code.

Common Errors

Error	Cause	Fix
`Cannot find module`	Missing dependency	Run `bun install`
`Top-level await`	Using await outside async	Wrap in async function or use `.mts`
`--watch not working`	Flag in wrong position	Put flag before `run`

When to Load References

Load references/bunfig.md when:

Configuring bunfig.toml
Setting up test configuration
Configuring package manager behavior
Setting JSX options

Load references/cli-flags.md when:

Need complete CLI flag reference
Configuring advanced runtime options
Setting up debugging

Load references/module-resolution.md when:

Troubleshooting import errors
Configuring path aliases
Understanding Bun's resolution algorithm

Weekly Installs

–

Repository

secondsky/claude-skills

GitHub Stars

First Seen

–

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

107,800 周安装