Bun 运行时旨在快速启动与高效运行。 Bun 使用由 Apple 为 Safari 开发的 JavaScriptCore 引擎。它通常比 Node.js 和基于 Chromium 的浏览器所使用的 V8 引擎启动和运行得更快。Bun 的转译器和运行时使用 Rust 编写。在 Linux 上，Bun 的启动速度比 Node.js 快 4 倍。

命令	时间
`bun hello.js`	`5.2ms`
`node hello.js`	`25.1ms`

该基准测试在 Linux 上运行 Hello World 脚本。

运行文件

使用 bun run 执行源文件。

terminal

bun run index.js

Bun 无需配置即可支持 TypeScript 和 JSX。Bun 会在运行每个文件之前，使用原生的转译器即时转译文件。

terminal

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

或者，你可以省略 run 关键字，使用裸命令，行为完全相同。

terminal

bun index.tsx
bun index.js

`--watch`

使用 --watch 标志可以以监听模式运行文件。

terminal

bun --watch run index.tsx

使用 bun run 时，Bun 的标志如 --watch 应紧跟在 bun 后面。

bun --watch run dev # ✔️ 推荐这样写
bun run dev --watch # ❌ 不推荐这样写

命令末尾的标志会被 bun 忽略，并传递给 "dev" 脚本本身。

运行 `package.json` 脚本

与 npm run <script> 或 yarn <script> 类似

bun [bun 标志] run <script> [脚本标志]

你的 package.json 可以定义与 shell 命令对应的命名 "scripts"。

package.json

{
  // ... 其他字段
  "scripts": {
    "clean": "rm -rf dist && echo 'Done.'",
    "dev": "bun server.ts"
  }
}

用 bun run <script> 执行这些脚本。

terminal

bun run clean
rm -rf dist && echo 'Done.'

Cleaning...
Done.

Bun 在子 Shell 中执行脚本命令。在 Linux 和 macOS 上，它会按以下顺序检查 Shell，并使用找到的第一个：bash、sh、zsh。在 Windows 上，它使用 Bun Shell 来支持类似 bash 的语法和许多常用命令。

⚡️ Linux 上 npm run 的启动时间约为 170ms；Bun 仅需 6ms。

你也可以使用更短的命令 bun <script> 来运行脚本。如果内置的 bun 命令与脚本同名，则优先使用内置命令；此时请使用明确的 bun run <script> 来运行包脚本。

terminal

bun run dev

要查看可用脚本列表，无需参数直接运行 bun run。

terminal

bun run

quickstart scripts:

 bun run clean
   rm -rf dist && echo 'Done.'

 bun run dev
   bun server.ts

2 scripts

Bun 支持生命周期钩子。例如，如果定义了 preclean 和 postclean，则 bun run clean 会依次运行它们。如果 pre<script> 执行失败，Bun 不会运行脚本本身。

`--bun`

通常 package.json 脚本会引用本地安装的 CLI，如 vite 或 next。这些 CLI 通常是带有 shebang 的 JavaScript 文件，用于指示使用 node 执行。

cli.js

#!/usr/bin/env node

// 执行相关操作

默认情况下，Bun 遵循此 shebang，并使用 node 执行脚本。--bun 标志会覆盖此设置：CLI 将使用 Bun 而不是 Node.js 运行。

terminal

bun run --bun vite

过滤执行

在 monorepo 中，--filter 参数可以一次在多个包中运行脚本。 bun run --filter <name_pattern> <script> 会在名称匹配 <name_pattern> 的每个包中执行 <script>。例如，如果你有包含名为 foo、bar 和 baz 的包的子目录，运行

terminal

bun run --filter 'ba*' <script>

会在 bar 和 baz 中执行 <script>，但不会在 foo 中执行。请参阅 --filter。

`bun run -` 从 stdin 管道执行代码

bun run - 从 stdin 读取 JavaScript、TypeScript、TSX 或 JSX，并在不先写入临时文件的情况下执行。

terminal

echo "console.log('Hello')" | bun run -

Hello

你也可以用 bun run - 把文件重定向给 Bun。例如，把 .js 文件当作 .ts 文件运行：

terminal

echo "console.log!('This is TypeScript!' as any)" > secretly-typescript.js
bun run - < secretly-typescript.js

This is TypeScript!

bun run - 会将所有输入视为支持 JSX 的 TypeScript。

`bun run --console-depth`

用 --console-depth 标志控制 console.log() 输出中对象检查的深度。

terminal

bun --console-depth 5 run index.tsx

--console-depth 设置 console.log() 输出中嵌套对象的显示深度。默认深度为 2。更高的值会显示更多嵌套属性，但对于复杂对象可能会产生冗长的输出。

console.ts

const nested = { a: { b: { c: { d: "deep" } } } };
console.log(nested);
// 使用 --console-depth 2（默认值）：{ a: { b: { c: [Object] } } }
// 使用 --console-depth 4：{ a: { b: { c: { d: 'deep' } } } }

`bun run --smol`

在内存受限环境中，使用 --smol 标志以降低内存使用，但会降低性能。

terminal

bun --smol run index.tsx

--smol 会使垃圾回收器更频繁地运行，这可能会降低执行速度。无论是否使用 --smol 标志，Bun 都会根据可用内存（考虑 cgroup 和其他内存限制）调整垃圾回收器的堆大小，因此该标志主要适用于希望堆增长得更慢的情况。

解析顺序

绝对路径以及以 ./ 或 .\\ 开头的路径始终作为源文件执行。除非使用 bun run，否则具有允许扩展名的名称会解析为文件，而不是 package.json 脚本。当 package.json 脚本与文件同名时，bun run 会优先选择脚本。完整的解析顺序如下：

package.json 脚本：bun run build
源文件：bun run src/main.js
项目依赖包中的二进制文件：bun add eslint && bun run eslint
（仅限 bun run）系统命令：bun run ls

CLI 用法

bun run <文件或脚本>

常规执行选项

boolean

不打印脚本命令

boolean

如果入口点不存在，则退出且不报错

string

将参数作为脚本执行。别名：-e

string

将参数作为脚本执行并打印结果。别名：-p

boolean

显示此菜单后退出。别名：-h

工作空间管理

number

default:"10"

使用 —filter 时显示的脚本输出行数（默认：10）。设置为 0 显示所有行

string

在匹配该模式的所有工作空间包中运行脚本。别名：-F

boolean

在所有工作空间包（来自 package.json 中的 workspaces 字段）中运行脚本

boolean

并发运行多个脚本或工作空间脚本，并带有前缀输出

boolean

依次运行多个脚本或工作空间脚本，并带有前缀输出

boolean

使用 —parallel 或 —sequential 时，当某脚本失败，继续执行其他脚本

运行时及进程控制

boolean

强制脚本或包使用 Bun 运行时而非 Node.js（通过软链接 node）。别名：-b

string

控制 package.json 脚本所用的 shell，支持 bun 或 system

boolean

打开兼容 Node.js 的 REPL（node:repl）。与 -e 结合使用时，会启动 REPL，然后执行脚本。在 —interactive 下，-e 是原始 JavaScript（与 node -i -e 的行为一致）；如需使用 TypeScript，请使用 bun repl。这与 bun repl 不同，后者是 Bun 的原生 REPL。

boolean

使用更少内存，但更频繁地进行垃圾回收

boolean

在全局对象上暴露 gc()。对 Bun.gc() 无影响

boolean

抑制所有自定义弃用警告

boolean

确定弃用警告是否会导致错误

string

设置进程标题

boolean

强制将 Buffer.allocUnsafe(size) 创建的缓冲区填充为零

boolean

调用 process.dlopen 时抛出错误，并禁用导出条件 node-addons

string

以下之一：strict、throw、warn、none，或 warn-with-error-code

number

default:"2"

设置 console.log 对象检查的默认深度（默认：2）

开发工作流

boolean

文件变更时自动重启进程

boolean

在 Bun 运行时、测试运行器或打包器中启用自动重载

boolean

在启用 —hot 或 —watch 时，禁止重新加载时清屏

调试

string

激活 Bun 的调试器

string

激活 Bun 的调试器，执行前等待连接

string

激活 Bun 的调试器，在代码第一行设置断点并等待

依赖与模块解析

string

在其他模块加载之前导入模块。别名：-r

string

—preload 别名，为 Node.js 兼容性设计

string

—preload 别名，为 Node.js 兼容性设计

boolean

禁用 Bun 运行时自动安装

string

default:"auto"

配置自动安装行为。值为 auto（默认，node_modules 不存在时自动安装）， fallback（缺失包时安装），force（始终安装）

boolean

执行时自动安装依赖。等同于 —install=fallback

boolean

跳过 Bun 运行时中的包陈旧检查，优先从磁盘解析

boolean

使用最新匹配版本包，始终检查 npm

string

传递自定义条件以进行解析

string

在 package.json 中查找的主要字段，默认依赖于 —target

boolean

解析文件时保留符号链接

boolean

解析主入口点时保留符号链接

string

default:".tsx,.ts,.jsx,.js,.json"

默认值：.tsx,.ts,.jsx,.js,.json

转译与语言特性

string

指定自定义 tsconfig.json，默认 $cwd/tsconfig.json

string

解析时替换 K:V，例如 —define process.env.NODE_ENV:“development”。值以 JSON 格式解析。别名：-d

string

移除函数调用，例如 —drop=console 会移除所有 console.* 调用

string

通过 .ext:loader 解析文件，例如 —loader .js:jsx。有效的加载器包括 js、 jsx、ts、tsx、json、toml、text、 file、wasm、napi。别名：-l

boolean

禁止在打包器、转译器和运行时执行宏

string

改变使用经典 JSX 运行时编译 JSX 元素时调用的函数

string

改变编译 JSX 片段时调用的函数

string

default:"react"

声明用于导入 jsx 和 jsxs 工厂函数的模块说明符。默认值：react

string

default:"automatic"

automatic（默认）或 classic

boolean

将 JSX 元素视为具有副作用（禁用纯注释）

boolean

忽略诸如 @PURE 的树摇注释

网络与安全

number

设置 Bun.serve 的默认端口

string

加载代码时对 URL 进行预连接

number

default:"16384"

设置 HTTP 头最大字节数，默认 16KiB

string

default:"verbatim"

设置 DNS 查询结果的默认顺序。有效值：verbatim（默认）、ipv4first、 ipv6first

boolean

使用系统的受信任证书颁发机构

boolean

使用 OpenSSL 的默认 CA 存储

boolean

使用捆绑的 CA 存储

boolean

启动时预连接 $REDIS_URL

boolean

启动时预连接 PostgreSQL

string

设置 HTTP 请求的默认 User-Agent 头

全局配置与上下文

string

从指定文件加载环境变量

string

用于解析文件和入口点的绝对路径。此选项只会更改进程的 cwd

string

指定 Bun 配置文件路径。默认 $cwd/bunfig.toml。别名：-c

示例

运行一个 JavaScript 或 TypeScript 文件：

bun run ./index.js
bun run ./index.tsx

运行 package.json 脚本：

bun run dev
bun run lint

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

Bun 运行时

运行文件

`--watch`

运行 `package.json` 脚本

`--bun`

过滤执行

`bun run -` 从 stdin 管道执行代码

`bun run --console-depth`

`bun run --smol`

解析顺序

CLI 用法

常规执行选项

工作空间管理

运行时及进程控制

开发工作流

调试

依赖与模块解析

转译与语言特性

网络与安全

全局配置与上下文

示例

​运行文件

​--watch

​运行 package.json 脚本

​--bun

​过滤执行

​bun run - 从 stdin 管道执行代码

​bun run --console-depth

​bun run --smol

​解析顺序

​CLI 用法

​常规执行选项

​工作空间管理

​运行时及进程控制

​开发工作流

​调试

​依赖与模块解析

​转译与语言特性

​网络与安全

​全局配置与上下文

​示例

运行文件

`--watch`

运行 `package.json` 脚本

`--bun`

过滤执行

`bun run -` 从 stdin 管道执行代码

`bun run --console-depth`

`bun run --smol`

解析顺序

CLI 用法

常规执行选项

工作空间管理

运行时及进程控制

开发工作流

调试

依赖与模块解析

转译与语言特性

网络与安全

全局配置与上下文

示例