Bun 运行时旨在快速启动与高效运行。底层，Bun 使用了由 Apple 为 Safari 开发的 JavaScriptCore 引擎。在大多数情况下，启动和运行性能均优于 Node.js 和基于 Chromium 浏览器使用的 V8 引擎。其转译器与运行时均用现代高性能语言 Zig 编写。在 Linux 上，启动速度比 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 # ❌ 不推荐这样写

命令末尾的标志会被忽略，并传递给 "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 使用 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 执行。

https://mintcdn.com/ikxin/RzFFGbzo0-4huILA/icons/javascript.svg?fit=max&auto=format&n=RzFFGbzo0-4huILA&q=85&s=e1a9947d6e369be0e97814b29cf9f8cd

cli.js

#!/usr/bin/env node

// do stuff

默认情况下，Bun 会尊重此 shebang，用 node 执行该脚本。你可用 --bun 标志覆写此行为。对于基于 Node.js 的 CLI，将用 Bun 代替 Node.js 执行。

terminal

bun run --bun vite

过滤执行

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

terminal

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

会在 bar 和 baz 中执行 <script>，而不会在 foo 中执行。更多详情见文档页 filter。

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

bun run - 允许从标准输入读取 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.log() 中显示对象的嵌套层数。默认深度是 2。更高的值显示更多嵌套属性，但复杂对象输出可能较冗长。

https://mintcdn.com/ikxin/RzFFGbzo0-4huILA/icons/typescript.svg?fit=max&auto=format&n=RzFFGbzo0-4huILA&q=85&s=a3dffd2241f05776d3bd25171d0c5a79

console.ts

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

`bun run --smol`

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

terminal

bun --smol run index.tsx

这会导致垃圾回收更频繁运行，可能减慢执行速度。但在内存有限环境中很有用。Bun 会基于可用内存（考虑 cgroups 和其他内存限制）自动调整垃圾回收堆大小，有无 --smol 标志，故此选项主要适合希望堆增长更缓慢的情况。

解析顺序

绝对路径及以 ./ 或 .\\ 开头的路径总是作为源文件执行。除非使用 bun run，运行带允许扩展名的文件优先使用该文件，而非 package.json 脚本。当存在同名 package.json 脚本与文件时，bun run 优先执行 package.json 脚本。完整解析顺序为：

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

CLI 用法

bun run <文件或脚本>

常规执行选项

--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 字段）中运行脚本

运行时及进程控制

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

使用最新匹配版本包，始终检查 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 头最大字节数，默认 16KiB

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

解析文件 & 入口点的绝对路径。仅更改进程的当前工作目录

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

常规执行选项

工作空间管理

运行时及进程控制

开发工作流

调试

依赖与模块解析

转译与语言特性

网络与安全

全局配置与上下文

示例

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

​运行文件

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

常规执行选项

工作空间管理

运行时及进程控制

开发工作流

调试

依赖与模块解析

转译与语言特性

网络与安全

全局配置与上下文

示例