Bun 运行时旨在快速启动与高效运行。 Bun 使用 JavaScriptCore 引擎，该引擎由 Apple 为 Safari 开发。JavaScriptCore 通常比 V8 启动和运行得更快，V8 是 Node.js 和基于 Chromium 的浏览器所使用的引擎。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.'

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

...
package.json scripts (2 found):
  $ bun run clean
    rm -rf dist && echo 'Done.'

  $ bun run dev
    bun server.ts

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 <pattern> <script> 会在 <pattern> 选中的每个包中执行 <script>。模式可以是包名 glob、./path、{dir} 目录或类似 foo... 的依赖关系。例如，如果你有几个子目录，其中包含名为 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 设置 Bun 在 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 都会根据可用内存（考虑 cgroups 和其他内存限制）调整垃圾回收器的堆大小。因此，该标志主要适用于希望堆增长得更慢的情况。

解析顺序

Bun 始终将绝对路径以及以 ./ 或 .\\ 开头的路径作为源文件执行。除非使用 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:"0"

使用 —filter 时，将每个脚本的输出截断为最后 N 行。默认值 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 或 bun:ffi cc()，则抛出错误，并禁用导出条件 node-addons

boolean

如果调用 bun:ffi cc()，则抛出错误（禁用 C 编译器）

string

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

number

default:"2"

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

开发工作流

boolean

文件变更时自动重启进程

string

default:"SIGTERM"

当 —watch 重启进程时运行其处理程序的信号

boolean

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

boolean

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

调试

string

激活 Bun 的调试器

string

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

string

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

依赖与模块解析

string

在 Bun 加载其他模块之前导入一个模块。别名：-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 中查找的主字段

boolean

解析文件时保留符号链接

boolean

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

string

默认值：.tsx,.ts,.jsx,.cts,.cjs,.js,.mjs,.mts,.json,.node

转译与语言特性

string

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

string

解析时替换 K:V，例如 —define process.env.NODE_ENV:“development”。Bun 会将值解析为 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 用法

常规执行选项

工作空间管理

运行时及进程控制

开发工作流

调试

依赖与模块解析

转译与语言特性

网络与安全

全局配置与上下文

示例