bun run script.ts build

命令简介

bun run 是 README 的命令执行入口，一身两职：

用法	行为
`bun run <file>`	直接执行 JS/TS 文件，TS 原生转译，无需 tsc/编译步骤
`bun run <name>`	执行 `package.json` 的 `scripts.<name>`

所以 bun run script.ts build 的含义是：运行当前目录下的 script.ts 文件，并把 build 作为命令行参数传入。脚本内通过 process.argv.slice(2) 拿到 ["build"]。

与 npm run 的关键差异：

传参不需要 -- 分隔符（npm run 传参要 npm run xxx -- build）
bun run 可直接跑 .ts 文件，npm run 只能跑 shell 命令
启动速度显著更快（无 npm CLI 自身的 Node 启动开销）

完整示例教程

配套项目已存档：raw/repos/bun-run-demo/（bun 1.3.14 实测，全部命令均实际执行通过）。

Step 1：项目结构

bun-run-demo/
├── package.json      # scripts: build / start
├── script.ts         # argv 驱动的 CLI 脚本
└── src/
    ├── index.ts      # 入口
    └── utils.ts      # 纯函数模块

script.ts：

const mode = process.argv[2] ?? "dev";
console.log(`build mode: ${mode}`);
console.log(`all args: ${JSON.stringify(process.argv.slice(2))}`);

package.json：

{
  "name": "bun-run-demo",
  "type": "module",
  "scripts": {
    "build": "bun build src/index.ts --outdir dist --target bun",
    "start": "bun dist/index.js"
  }
}

Step 2：直接运行文件 + 传参（命令本体）

$ bun run script.ts build
build mode: build
all args: ["build"]
 
$ bun run script.ts build --env prod
build mode: build
all args: ["build","--env","prod"]

script.ts 后的所有参数原样进入 process.argv，多个参数依次追加
bun script.ts build（省略 run）效果相同
文件不存在时报 error: Module not found "xxx"，而非静默当脚本名处理

Step 3：直接运行 TS 源码（免编译）

$ bun run src/index.ts
user: Alice (30)
sum: 10
runtime: 1.3.14

src/index.ts 直接 import 了 ./utils（TS 模块），bun 原生转译执行，全局对象 Bun.version 可用。这一步不需要 tsc、不需要 tsconfig.json。

Step 4：bun run build —— 执行 scripts 条目

$ bun run build
$ bun build src/index.ts --outdir dist --target bun
Bundled 2 modules in 24ms
 
  index.js  337 bytes  (entry point)

build 不是文件而是 scripts 条目，bun 执行其中的 bun build 打包命令：把 src/index.ts + src/utils.ts 两个模块 bundle 成单文件 dist/index.js，24ms 完成。

Step 5：运行打包产物

$ bun run start
user: Alice (30)
sum: 10
runtime: 1.3.14

产物用 --target bun 生成，可用 Bun.* API；若要跑在 Node 上，打包时改用 --target node。

文件与脚本的优先级（易踩坑）

当目录里同时存在 build.ts 文件和 scripts.build 条目时（已实测）：

命令	实际执行
`bun run build`	scripts 条目优先
`bun run build.ts` / `bun run ./build.ts`	文件
`bun build.ts`	文件（裸 `bun` 形式文件优先）

即 bun run <裸名> 先查 scripts；带扩展名或路径前缀则按文件处理。

常用 flags（bun run —help 精选）

flag	说明
`--watch`	文件变化自动重启进程（适合开发循环）
`--hot`	运行时热重载（不重启进程，状态保留）
`--env-file=<file>`	加载指定 env 文件；`.env` 默认自动加载，`--no-env-file` 可关
`--parallel` / `--sequential`	并行/串行执行多个脚本，Foreman 风格输出
`--silent`	不打印 `$ <script>` 命令行本身
`--if-present`	入口不存在时静默退出（CI 可选步骤常用）
`-b, --bun`	强制 scripts 用 bun 运行时而非 node
`-r, --preload=<val>`	在其他模块前预加载模块（如注入配置）
`--inspect[=-wait/-brk]`	启动调试器
`--cpu-prof` / `--heap-prof`	CPU/堆性能分析
`--smol`	省内存模式（GC 更频繁）
`--define=K:V`	编译期常量替换，如 `--define process.env.NODE_ENV:"production"`

bun run --watch script.ts build       # 开发时改代码自动重跑
bun run --parallel dev lint           # 同时跑多个 scripts
bun run --silent deploy               # 隐藏 $ 前缀行

与相邻命令的关系

命令	定位
`bun run <file/name>`	本页主题：跑文件或 scripts
`bun build`	打包（`bun run build` 里执行的正是它）
`bun x` / bunx	临时执行 npm 包二进制，无需安装
`npm run`	只跑 scripts 条目，传参需 `--`，不能直接跑 .ts

zhaoweiguo 的知识库

目录