Shell - Bun

Bun Shell 让使用 JavaScript 和 TypeScript 编写 shell 脚本变得有趣。它是一个跨平台的类 bash shell，并支持与 JavaScript 的互操作。快速入门：

index.ts

import { $ } from "bun";

const response = await fetch("https://example.com");

// 使用 Response 作为 stdin。
await $`cat < ${response} | wc -c`; // 1256

特性

跨平台：可在 Windows、Linux 和 macOS 上运行。无需安装 rimraf 或 cross-env，您可以使用 Bun Shell。常见 shell 命令如 ls、cd 和 rm 都已原生实现。
熟悉：Bun Shell 是一个类 bash shell，支持重定向、管道和环境变量。
Glob 模式：原生支持 glob 模式，包括 **、* 和 {expansion}。
模板字面量：模板字面量执行 shell 命令并插值变量和表达式。
安全性：Bun Shell 默认转义所有字符串，防止 shell 注入攻击。
JavaScript 互操作：使用 Response、ArrayBuffer、Blob、Bun.file(path) 和其他 JavaScript 对象作为 stdin、stdout 和 stderr。
Shell 脚本：Bun Shell 运行 shell 脚本（.bun.sh 文件）。
自定义解释器：Bun Shell 是一个小型编程语言，拥有自己的词法分析器、解析器和解释器，使用 Rust 编写。

快速入门

最简单的 shell 命令是 echo。要运行它，请使用 $ 模板字面量标签：

import { $ } from "bun";

await $`echo "Hello World!"`; // Hello World!

默认情况下，shell 命令会打印到 stdout。要静默输出，请调用 .quiet()：

import { $ } from "bun";

await $`echo "Hello World!"`.quiet(); // 无输出

要将命令输出作为文本读取，请使用 .text()：

import { $ } from "bun";

// .text() 会自动为您调用 .quiet()
const welcome = await $`echo "Hello World!"`.text();

console.log(welcome); // Hello World!\n

默认情况下，await 会返回 stdout 和 stderr 作为 Buffer。

import { $ } from "bun";

const { stdout, stderr } = await $`echo "Hello!"`.quiet();

console.log(stdout); // Buffer(7) [ 72, 101, 108, 108, 111, 33, 10 ]
console.log(stderr); // Buffer(0) []

错误处理

默认情况下，非零退出代码会抛出错误。ShellError 包含所运行命令的信息。

import { $ } from "bun";

try {
  const output = await $`something-that-may-fail`.text();
  console.log(output);
} catch (err) {
  console.log(`Failed with code ${err.exitCode}`);
  console.log(err.stdout.toString());
  console.log(err.stderr.toString());
}

.nothrow() 禁用抛出。您可以自己检查结果的 exitCode。

import { $ } from "bun";

const { stdout, stderr, exitCode } = await $`something-that-may-fail`.nothrow().quiet();

if (exitCode !== 0) {
  console.log(`Non-zero exit code ${exitCode}`);
}

console.log(stdout);
console.log(stderr);

要更改所有命令的默认行为，请在 $ 函数本身上调用 .nothrow() 或 .throws(boolean)。

import { $ } from "bun";
// shell promises 不会抛出，这意味着您必须
// 在每个 shell 命令上手动检查 `exitCode`。
$.nothrow(); // 等同于 $.throws(false)

// 默认行为，非零退出代码会抛出错误
$.throws(true);

// $.nothrow() 的别名
$.throws(false);

await $`something-that-may-fail`; // 不会抛出异常

重定向

使用典型的 Bash 运算符重定向命令的输入或输出：

< 重定向 stdin
> 或 1> 重定向 stdout
2> 重定向 stderr
&> 重定向 stdout 和 stderr 两者
>> 或 1>> 重定向 stdout，追加到目标，而不是覆盖
2>> 重定向 stderr，追加到目标，而不是覆盖
&>> 重定向 stdout 和 stderr 两者，追加到目标，而不是覆盖
1>&2 将 stdout 重定向到 stderr（写入 stdout 的内容改为写入 stderr）
2>&1 将 stderr 重定向到 stdout（写入 stderr 的内容改为写入 stdout）

Bun Shell 还支持从 JavaScript 对象重定向输入和输出。

示例：将输出重定向到 JavaScript 对象（`>`）

要将 stdout 重定向到 JavaScript 对象，请使用 > 运算符：

import { $ } from "bun";

const buffer = Buffer.alloc(100);
await $`echo "Hello World!" > ${buffer}`;

console.log(buffer.toString()); // Hello World!\n

您可以将输出重定向到这些 JavaScript 对象：

Buffer、Uint8Array、Uint16Array、Uint32Array、Int8Array、Int16Array、Int32Array、Float32Array、Float64Array、ArrayBuffer、SharedArrayBuffer（写入底层缓冲区）
Bun.file(path)、Bun.file(fd)（写入文件）

示例：从 JavaScript 对象重定向输入（`<`）

要将 JavaScript 对象用作 stdin，请使用 < 运算符：

import { $ } from "bun";

const response = new Response("hello i am a response body");

const result = await $`cat < ${response}`.text();

console.log(result); // hello i am a response body

您可以从这些 JavaScript 对象重定向输入：

Buffer、Uint8Array、Uint16Array、Uint32Array、Int8Array、Int16Array、Int32Array、Float32Array、Float64Array、ArrayBuffer、SharedArrayBuffer（从底层缓冲区读取）
Bun.file(path)、Bun.file(fd)（从文件读取）
Response（从 body 读取）

示例：重定向 stdin -> 文件

import { $ } from "bun";

await $`cat < myfile.txt`;

示例：重定向 stdout -> 文件

import { $ } from "bun";

await $`echo bun! > greeting.txt`;

示例：重定向 stderr -> 文件

import { $ } from "bun";

await $`bun run index.ts 2> errors.txt`;

示例：重定向 stderr -> stdout

import { $ } from "bun";

// 将 stderr 重定向到 stdout，因此所有输出
// 都会在 stdout 上可用
await $`bun run ./index.ts 2>&1`;

示例：重定向 stdout -> stderr

import { $ } from "bun";

// 将 stdout 重定向到 stderr，因此所有输出
// 都会在 stderr 上可用
await $`bun run ./index.ts 1>&2`;

管道（`|`）

与 bash 类似，您可以将一个命令的输出通过管道传递给另一个命令：

import { $ } from "bun";

const result = await $`echo "Hello World!" | wc -w`.text();

console.log(result); // 2\n

您也可以与 JavaScript 对象配合使用管道：

import { $ } from "bun";

const response = new Response("hello i am a response body");

const result = await $`cat < ${response} | wc -w`.text();

console.log(result); // 6\n

命令替换（`$(...)`）

命令替换将另一个命令的输出插入到当前脚本中：

import { $ } from "bun";

// 打印当前提交的哈希值
await $`echo Hash of current commit: $(git rev-parse HEAD)`;

输出作为文本插入，因此您可以使用它来声明 shell 变量：

import { $ } from "bun";

await $`
  REV=$(git rev-parse HEAD)
  docker built -t myapp:$REV
  echo Done building docker image "myapp:$REV"
`;

由于 Bun 内部使用输入模板字面量的特殊 raw 属性，因此使用反引号语法进行命令替换将不起作用：

import { $ } from "bun";

await $`echo \`echo hi\``;

它不会打印：

hi

而是打印：

`echo hi`

请改用 $(...) 语法。

环境变量

像 bash 一样设置环境变量：

import { $ } from "bun";

await $`FOO=foo bun -e 'console.log(process.env.FOO)'`; // foo\n

使用字符串插值来设置值：

import { $ } from "bun";

const foo = "bar123";

await $`FOO=${foo + "456"} bun -e 'console.log(process.env.FOO)'`; // bar123456\n

输入默认被转义，防止 shell 注入攻击：

import { $ } from "bun";

const foo = "bar123; rm -rf /tmp";

await $`FOO=${foo} bun -e 'console.log(process.env.FOO)'`; // bar123; rm -rf /tmp\n

更改环境变量

默认情况下，所有命令都使用 process.env 作为其环境变量。要更改单个命令的环境变量，请调用 .env()：

import { $ } from "bun";

await $`echo $FOO`.env({ ...process.env, FOO: "bar" }); // bar

要更改所有命令的默认环境变量，请调用 $.env：

import { $ } from "bun";

$.env({ FOO: "bar" });

// 全局设置的 $FOO
await $`echo $FOO`; // bar

// 局部设置的 $FOO
await $`echo $FOO`.env({ FOO: "baz" }); // baz

要将环境变量重置为默认值，请调用不带参数的 $.env()：

import { $ } from "bun";

$.env({ FOO: "bar" });

// 全局设置的 $FOO
await $`echo $FOO`; // bar

// 局部设置的 $FOO
await $`echo $FOO`.env(undefined); // ""

更改工作目录

要更改命令的工作目录，请将字符串传递给 .cwd()：

import { $ } from "bun";

await $`pwd`.cwd("/tmp"); // /tmp

要更改所有命令的默认工作目录，请调用 $.cwd：

import { $ } from "bun";

$.cwd("/tmp");

// 全局设置的工作目录
await $`pwd`; // /tmp

// 局部设置的工作目录
await $`pwd`.cwd("/"); // /

读取输出

要将命令的输出作为字符串读取，请使用 .text()：

import { $ } from "bun";

const result = await $`echo "Hello World!"`.text();

console.log(result); // Hello World!\n

将输出读取为 JSON

要将命令的输出作为 JSON 读取，请使用 .json()：

import { $ } from "bun";

const result = await $`echo '{"foo": "bar"}'`.json();

console.log(result); // { foo: "bar" }

逐行读取输出

要逐行读取命令的输出，请使用 .lines()：

import { $ } from "bun";

for await (let line of $`echo "Hello World!"`.lines()) {
  console.log(line); // Hello World!
}

您也可以在已完成的命令上使用 .lines()：

import { $ } from "bun";

const search = "bun";

for await (let line of $`cat list.txt | grep ${search}`.lines()) {
  console.log(line);
}

将输出读取为 Blob

要将命令的输出作为 Blob 读取，请使用 .blob()：

import { $ } from "bun";

const result = await $`echo "Hello World!"`.blob();

console.log(result); // Blob(13) { size: 13, type: "text/plain" }

内置命令

为跨平台兼容性，Bun Shell 实现了一组内置命令，此外还可以从 PATH 环境变量读取命令。

cd：更改工作目录
ls：列出目录中的文件（支持 -l 长列表格式）
rm：删除文件和目录
echo：打印文本
pwd：打印工作目录
bun：在 bun 中运行 bun
cat
touch
mkdir
which
mv
exit
true
false
yes
seq
dirname
basename

部分实现：

mv：移动文件和目录（缺少跨设备支持）

尚未实现，但已计划：

查看 Issue #9716 获取完整列表。

工具函数

Bun Shell 还实现了一组用于处理 shell 的工具函数。

`$.braces`（花括号展开）

$.braces 实现了 shell 命令的花括号展开：

import { $ } from "bun";

await $.braces(`echo {1,2,3}`);
// => ["echo 1", "echo 2", "echo 3"]

`$.escape`（转义字符串）

将 Bun Shell 的转义逻辑暴露为函数：

import { $ } from "bun";

console.log($.escape('$(foo) `bar` "baz"'));
// => "\$(foo) \`bar\` \"baz\""

要跳过转义，请将字符串包装在 { raw: 'str' } 对象中：

import { $ } from "bun";

await $`echo ${{ raw: '$(foo) `bar` "baz"' }}`;
// => bun: command not found: foo
// => bun: command not found: bar
// => baz

`.sh` 文件加载器

对于简单的 shell 脚本，您可以使用 Bun Shell 代替 /bin/sh。将带有 .sh 扩展名的文件传递给 bun：

script.sh

echo "Hello World! pwd=$(pwd)"

terminal

bun ./script.sh

Hello World! pwd=/home/demo

Bun Shell 脚本是跨平台的，因此它们可以在 Windows 上运行：

powershell

bun .\script.sh

Hello World! pwd=C:\Users\Demo

实现说明

Bun Shell 是一个用 Rust 实现的小型编程语言，拥有手写的词法分析器、解析器和解释器。与 bash、zsh 和其他 shell 不同，Bun Shell 并发运行操作。

Bun Shell 的安全机制

Bun Shell 有意不调用系统 shell（如 /bin/sh）。它是 bash 的重新实现，运行在同一个 Bun 进程中。解析命令参数时，它会将所有插值变量视为单个字面量字符串。这可以防止命令注入：

import { $ } from "bun";

const userInput = "my-file.txt; rm -rf /";

// 安全：`userInput` 被视为单个引用字符串
await $`ls ${userInput}`;

这里，userInput 被视为单个字符串，因此 ls 尝试读取名为 my-file.txt; rm -rf / 的单个目录的内容。

安全注意事项

虽然默认情况下防止了命令注入，但在某些场景下您仍需负责安全。与 Bun.spawn 或 node:child_process.exec() API 类似，您可以有意执行一个启动新 shell 的命令（例如 bash -c）并附带参数。当您这样做时，您移交了控制权，Bun 的内置保护不再适用于该新 shell 解释的字符串。

import { $ } from "bun";

const userInput = "world; touch /tmp/pwned";

// 不安全：您显式地用 `bash -c` 启动了一个新的 shell 进程。
// 这个新 shell 将执行 `touch` 命令。任何以这种方式传递的用户输入
// 必须严格清理。
await $`bash -c "echo ${userInput}"`;

参数注入

Bun Shell 无法知道外部命令如何解释其自身的命令行参数。攻击者可以提供目标程序识别为其自身选项或标志的输入，从而导致意外行为。

import { $ } from "bun";

// 格式化为 Git 命令行标志的恶意输入
const branch = "--upload-pack=echo pwned";

// 不安全：虽然 Bun 安全地将该字符串作为单个参数传递，
// 但 `git` 程序本身会看到并执行恶意标志。
await $`git ls-remote origin ${branch}`;

建议：在将用户提供的输入作为参数传递给外部命令之前，始终进行清理。验证参数是您应用程序的责任。

致谢

此 API 的大部分部分受到了 zx、dax 和 bnx 的启发。感谢这些项目的作者。

​特性

​快速入门

​错误处理

​重定向

​示例：将输出重定向到 JavaScript 对象（>）

​示例：从 JavaScript 对象重定向输入（<）

​示例：重定向 stdin -> 文件

​示例：重定向 stdout -> 文件

​示例：重定向 stderr -> 文件

​示例：重定向 stderr -> stdout

​示例：重定向 stdout -> stderr

​管道（|）

​命令替换（$(...)）

​环境变量

​更改环境变量

​更改工作目录

​读取输出

​将输出读取为 JSON

​逐行读取输出

​将输出读取为 Blob

​内置命令

​工具函数

​$.braces（花括号展开）

​$.escape（转义字符串）

​.sh 文件加载器

​实现说明

​Bun Shell 的安全机制

​安全注意事项

​参数注入

​致谢

特性

快速入门

错误处理

重定向

示例：将输出重定向到 JavaScript 对象（`>`）

示例：从 JavaScript 对象重定向输入（`<`）

示例：重定向 stdin -> 文件

示例：重定向 stdout -> 文件

示例：重定向 stderr -> 文件

示例：重定向 stderr -> stdout

示例：重定向 stdout -> stderr

管道（`|`）

命令替换（`$(...)`）

环境变量

更改环境变量

更改工作目录

读取输出

将输出读取为 JSON

逐行读取输出

将输出读取为 Blob

内置命令

工具函数

`$.braces`（花括号展开）

`$.escape`（转义字符串）

`.sh` 文件加载器

实现说明

Bun Shell 的安全机制

安全注意事项

参数注入

致谢