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 时，将 --watch 等 Bun 标志紧跟在 bun 之后。

bun --watch run dev # ✔️ 这样做
bun run dev --watch # ❌ 不要这样做

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

运行 `package.json` 脚本

对比 npm run <script> 或 yarn <script>

bun [bun flags] run <script> [script flags]

你的 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 遵循生命周期钩子。例如，bun run clean 会运行 preclean 和 postclean（如果已定义）。如果 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 标志控制控制台输出中对象检查的深度。

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 使垃圾回收器更频繁地运行，这可能会降低执行速度。Bun 会根据可用内存（考虑 cgroups 和其他内存限制）在有或没有 --smol 标志的情况下调整垃圾回收器的堆大小，因此该标志主要在你希望堆增长更慢时有用。

解析顺序

绝对路径和以 ./ 或 .\\ 开头的路径始终作为源文件执行。除非你使用 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 <file or script>

通用执行选项

--silent

boolean

不打印脚本命令

--if-present

boolean

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

--eval

string

将参数作为脚本求值。别名：-e

--print

string

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

--help

boolean

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

工作区管理

--elide-lines

number

default:"10"

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

--filter

string

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

--workspaces

boolean

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

--parallel

boolean

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

--sequential

boolean

依次运行多个脚本或工作区脚本，输出带前缀

--no-exit-on-error

boolean

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

运行时与进程控制

--bun

boolean

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

--shell

string

控制用于 package.json 脚本的 shell。支持 bun 或 system

--smol

boolean

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

--expose-gc

boolean

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

--no-deprecation

boolean

禁止所有自定义弃用警告的报告

--throw-deprecation

boolean

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

--title

string

设置进程标题

--zero-fill-buffers

boolean

强制 Buffer.allocUnsafe(size) 以零填充

--no-addons

boolean

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

--unhandled-rejections

string

可选 strict、throw、warn、none 或 warn-with-error-code

--console-depth

number

default:"2"

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

开发工作流

--watch

boolean

文件变化时自动重启进程

--hot

boolean

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

--no-clear-screen

boolean

启用 —hot 或 —watch 时禁用重载时清除终端屏幕

调试

--inspect

string

激活 Bun 的调试器

--inspect-wait

string

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

--inspect-brk

string

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

依赖与模块解析

--preload

string

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

--require

string

—preload 的别名，用于 Node.js 兼容性

--import

string

—preload 的别名，用于 Node.js 兼容性

--no-install

boolean

在 Bun 运行时中禁用自动安装

--install

string

default:"auto"

配置自动安装行为。可选：auto（默认，无 node_modules 时自动安装）、fallback（仅缺失包）、force（始终）

-i

boolean

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

--prefer-offline

boolean

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

--prefer-latest

boolean

在 Bun 运行时中使用最新的匹配版本，始终检查 npm

--conditions

string

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

--main-fields

string

在 package.json 中查找的主要字段。默认取决于 —target

--preserve-symlinks

boolean

解析文件时保留符号链接

--preserve-symlinks-main

boolean

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

--extension-order

string

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

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

转译与语言特性

--tsconfig-override

string

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

--define

string

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

--drop

string

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

--loader

string

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

--no-macros

boolean

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

--jsx-factory

string

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

--jsx-fragment

string

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

--jsx-import-source

string

default:"react"

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

--jsx-runtime

string

default:"automatic"

automatic（默认）或 classic

--jsx-side-effects

boolean

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

--ignore-dce-annotations

boolean

忽略树摇注解，例如 @PURE

网络与安全

--port

number

为 Bun.serve 设置默认端口

--fetch-preconnect

string

在代码加载时预连接到 URL

--max-http-header-size

number

default:"16384"

设置 HTTP 标头的最大大小（字节）。默认 16 KiB

--dns-result-order

string

default:"verbatim"

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

--use-system-ca

boolean

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

--use-openssl-ca

boolean

使用 OpenSSL 的默认 CA 存储

--use-bundled-ca

boolean

使用内置的 CA 存储

--redis-preconnect

boolean

启动时预连接到 $REDIS_URL

--sql-preconnect

boolean

启动时预连接到 PostgreSQL

--user-agent

string

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

全局配置与上下文

--env-file

string

从指定文件加载环境变量

--cwd

string

解析文件和入口点的绝对路径。这只是更改进程的 cwd

--config

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 用法

通用执行选项

工作区管理

运行时与进程控制

开发工作流

调试

依赖与模块解析

转译与语言特性

网络与安全

全局配置与上下文

示例