Web

Appearance

bun run ​

bun run 命令是 Bun 的核心功能之一，它让你能够执行 JavaScript/TypeScript 文件、package.json 脚本以及可执行包。无论你是初学者还是有经验的开发者，掌握这个命令都能显著提高你的开发效率。

为什么选择 Bun？性能优势解析 ​

Bun 的设计理念是快速启动，快速运行。作为一个新一代的 JavaScript 运行时，Bun 在性能方面有着显著的优势。

Bun 使用 Apple 为 Safari 开发的 [JavaScriptCore 引擎](https://developer.apple.com/documentation/javascriptcore)，而不是 Node.js 使用的 V8 引擎。它的转译器和运行时是用 Zig 这种现代高性能语言编写的。

启动速度对比 ​

在 Linux 系统上运行一个简单的 Hello World 脚本，Bun 的启动速度比 Node.js 快约 4 倍！

命令启动时间
bun hello.js5.2ms
node hello.js25.1ms

这种性能差异在日常开发中可以带来明显的效率提升，特别是当你需要频繁运行脚本或构建应用时。

运行文件 ​

INFO

与 Node.js 的 node <file> 命令类似

使用 bun run 来执行源文件：

bash
$ bun run index.js

Bun 的内置转译功能 ​

Bun 最强大的特性之一是内置支持 TypeScript 和 JSX，无需额外配置。每个文件在执行前都会通过 Bun 高性能的原生转译器进行即时转译。

bash
# 支持多种文件格式
$ bun run index.js
$ bun run index.jsx
$ bun run index.ts
$ bun run index.tsx

你还可以省略 run 关键字，使用更简洁的命令形式：

bash
$ bun index.tsx
$ bun index.js

文件监视模式 ​

开发时，你经常需要在文件变化时自动重新运行代码。Bun 提供了简单易用的 --watch 标志：

bash
$ bun --watch run index.tsx

使用 `bun run` 时，Bun 的标志（如 `--watch`）必须放在 `bun` 之后、`run` 之前：

bash
$ bun --watch run dev    # ✓ 正确方式
$ bun run dev --watch    # ✗ 错误方式（--watch 会被传递给 dev 脚本）

运行 package.json 脚本 ​

INFO

与 NPM 的 npm run <script> 或 Yarn 的 yarn <script> 命令类似

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

在 package.json 中，你可以定义各种命名脚本，每个脚本对应一个 shell 命令：

json
{
  "scripts": {
    "clean": "rm -rf dist && echo '清理完成！'",
    "dev": "bun server.ts"
  }
}

使用 bun run <script> 来执行这些脚本：

bash
$ bun run clean
 $ rm -rf dist && echo '清理完成！'
 清理中...
 清理完成！

执行环境 ​

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

Bun 在启动速度上远超 npm！在 Linux 上，`npm run` 的启动时间大约是 170ms，而 Bun 仅需 6ms！这种差异在日常开发中非常明显。

简化命令 ​

脚本也可以通过更短的命令 bun <script> 来运行。但如果有同名的 Bun 内置命令，则内置命令会优先执行。这种情况下，应使用更明确的 bun run <script> 命令。

bash
$ bun run dev

查看可用脚本 ​

想知道项目中有哪些可用脚本？只需运行不带参数的 bun run 命令：

bash
$ bun run
quickstart scripts:

 bun run clean
   rm -rf dist && echo '清理完成！'

 bun run dev
   bun server.ts

2 scripts

生命周期钩子 ​

Bun 尊重脚本的生命周期钩子。例如，运行 bun run clean 时，如果定义了 preclean 和 postclean，Bun 会自动执行它们。如果 pre<script> 失败，Bun 不会执行主脚本。

json
{
  "scripts": {
    "preclean": "echo '准备清理...'",
    "clean": "rm -rf dist",
    "postclean": "echo '清理完成！'"
  }
}

--bun 标志：以 Bun 运行 CLI ​

使用 Bun 运行 Node.js CLI 在项目中，我们经常使用本地安装的 CLI 工具，如 vite 或 next。这些 CLI 通常是标有 shebang 的 JavaScript 文件，指示它们应该使用 node 执行：
js
#!/usr/bin/env node

// 执行操作

默认情况下，Bun 会尊重这个 shebang 并使用 node 执行脚本。但你可以使用 --bun 标志覆盖这一行为，让基于 Node.js 的 CLI 工具使用 Bun 而不是 Node.js 运行：

bash
$ bun run --bun vite

在多包项目中过滤运行脚本 ​

在包含多个包的 monorepo 项目中，你可以使用 --filter 参数在多个包中同时执行脚本。

使用 bun run --filter <名称模式> <脚本> 在所有名称匹配 <名称模式> 的包中执行 <脚本>。

例如，如果你的子目录中包含名为 foo、bar 和 baz 的包，运行：

bash
bun run --filter 'ba*' <脚本>

这将在 bar 和 baz 中执行 <脚本>，但不会在 foo 中执行。

TIP

更多详细信息，请查看 filter 的文档页面。

从标准输入执行代码 ​

bun run - 允许你从标准输入读取 JavaScript、TypeScript、TSX 或 JSX 代码并执行它，无需先写入临时文件。

bash
$ echo "console.log('你好，世界！')" | bun run -
你好，世界！

你还可以使用 bun run - 将文件重定向到 Bun。例如，将 .js 文件作为 .ts 文件运行：

bash
$ echo "console.log!('这是 TypeScript!' as any)" > 实际是typescript.js
$ bun run - < 实际是typescript.js
这是 TypeScript!

为了方便，使用 bun run - 时，所有代码都将被视为具有 JSX 支持的 TypeScript。

内存优化选项：--smol ​

在内存受限的环境中，可以使用 --smol 标志以牺牲性能为代价减少内存使用：

bash
$ bun --smol run index.tsx

这会导致垃圾收集器更频繁地运行，这可能会减慢执行速度。但在内存有限的环境中，这是非常有用的。

WARNING

虽然 Bun 会自动根据可用内存（考虑到 cgroups 和其他内存限制）调整垃圾收集器的堆大小，但 --smol 标志主要用于你希望堆大小增长更慢的情况。

解析顺序 ​

当使用 Bun 执行命令时，Bun 按照特定顺序解析要运行的内容。下面是完整的解析顺序：

  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

绝对路径和以 `./` 或 `.\\` 开头的路径总是被作为源文件执行。除非使用 `bun run`，运行具有允许扩展名的文件时，会优先选择文件而不是 package.json 脚本。

当存在同名的 package.json 脚本和文件时，bun run 会优先选择 package.json 脚本。

Bun run 命令总结 ​

bun run [options] <script|file> [args...]

选项:
  --bun      启用 "bun" 子进程，覆盖脚本的 shebang
  --smol     优化内存使用（以牺牲性能为代价）
  --watch    在监视模式下运行，当文件更改时重新启动
  --cwd      设置工作目录

通过掌握 bun run 命令的各种用法，你可以显著提高开发效率，充分利用 Bun 的性能优势和功能特性。