Bun 运行时

使用 Bun 的快速运行时执行 JavaScript/TypeScript 文件、package.json 脚本和可执行包。

Bun 运行时设计为快速启动和快速运行。

在底层，Bun 使用 JavaScriptCore 引擎，这是由苹果为 Safari 开发的。在大多数情况下，启动和运行性能比 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 flags] run <script> [script flags]

您的 package.json 可以定义许多命名的 "scripts"，它们对应于 shell 命令。

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

// do stuff

默认情况下，Bun 遵循这个 shebang 并使用 node 执行脚本。但是，您可以使用 --bun 标志覆盖此行为。对于基于 Node.js 的 CLI，这将使用 Bun 而不是 Node.js 运行 CLI。

terminal

bun run --bun vite

过滤

在包含多个包的单一代码库中，您可以使用 --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 - 从标准输入管道传输代码

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.log() 输出中显示嵌套对象的深度。默认深度为 2。较高的值显示更多嵌套属性，但对于复杂对象可能产生冗长的输出。

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 脚本。完整的解析顺序是：

1. package.json 脚本，例如 bun run build
2. 源文件，例如 bun run src/main.js
3. 来自项目包的二进制文件，例如 bun add eslint && bun run eslint
4. （仅 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 字段）

运行时和进程控制

--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 头的最大大小（以字节为单位）。默认值为 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

从中解析文件和入口点的绝对路径。这只是更改进程的 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