Bun Shell 让使用 JavaScript 和 TypeScript 进行 shell 脚本编写变得有趣。它是一个跨平台的类 bash shell，具有无缝的 JavaScript 互操作性。
快速开始
import { $ } from "bun";
const response = await fetch("https://example.com");
// Use Response as 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 使用 Zig 编写，包括其词法分析器、解析器和解释器。Bun Shell 是一种小型编程语言。
快速上手
最简单的 shell 命令是 echo。要运行它，请使用 $ 模板字面量标签
import { $ } from "bun";
await $`echo "Hello World!"`; // Hello World!
默认情况下，shell 命令输出到 stdout。要静默输出，请调用 .quiet()
import { $ } from "bun";
await $`echo "Hello World!"`.quiet(); // No output
如果想以文本形式访问命令的输出怎么办？请使用 .text()
import { $ } from "bun";
// .text() automatically calls .quiet() for you
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 will not throw, meaning you will have to
// check for `exitCode` manually on every shell command.
$.nothrow(); // equivalent to $.throws(false)
// default behavior, non-zero exit codes will throw an error
$.throws(true);
// alias for $.nothrow()
$.throws(false);
await $`something-that-may-fail`; // No exception thrown
重定向
可以使用典型的 Bash 运算符*重定向*命令的*输入*或*输出*
<重定向 stdin>或1>重定向 stdout2>重定向 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 对象。
示例：将输出重定向到 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";
// redirects stderr to stdout, so all output
// will be available on stdout
await $`bun run ./index.ts 2>&1`;
示例：重定向 stdout（标准输出） -> stderr（标准错误输出）
import { $ } from "bun";
// redirects stdout to stderr, so all output
// will be available on 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";
// Prints out the hash of the current commit
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" });
// the globally-set $FOO
await $`echo $FOO`; // bar
// the locally-set $FOO
await $`echo $FOO`.env({ FOO: "baz" }); // baz
你可以通过调用不带参数的 $.env() 将环境变量重置为默认值
import { $ } from "bun";
$.env({ FOO: "bar" });
// the globally-set $FOO
await $`echo $FOO`; // bar
// the locally-set $FOO
await $`echo $FOO`.env(undefined); // ""
更改工作目录
你可以通过将字符串传递给 .cwd() 来更改命令的工作目录
import { $ } from "bun";
await $`pwd`.cwd("/tmp"); // /tmp
你可以通过调用 $.cwd 来更改所有命令的默认工作目录
import { $ } from "bun";
$.cwd("/tmp");
// the globally-set working directory
await $`pwd`; // /tmp
// the locally-set working directory
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: 列出目录中的文件rm: 删除文件和目录echo: 打印文本pwd: 打印工作目录bun: 在 bun 中运行 buncattouchmkdirwhichmvexittruefalseyesseqdirnamebasename
部分实现
mv: 移动文件和目录（缺少跨设备支持）
尚未实现，但已计划
- 有关完整列表，请参阅 Issue #9716。
实用工具
Bun Shell 还实现了一组用于处理 shell 的实用工具。
$.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 来运行 shell 脚本。
为此，只需在带有 .sh 扩展名的文件上使用 bun 运行脚本即可。
script.sh
echo "Hello World! pwd=$(pwd)"
bun ./script.shHello World! pwd=/home/demo使用 Bun Shell 的脚本是跨平台的，这意味着它们可以在 Windows 上运行
bun .\script.shHello World! pwd=C:\Users\Demo实现说明
Bun Shell 是 Bun 中使用 Zig 实现的小型编程语言。它包括手写的词法分析器、解析器和解释器。与 bash、zsh 和其他 shell 不同，Bun Shell 并发运行操作。