> ## Documentation Index
> Fetch the complete documentation index at: https://bun.ll1025.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# Spawn
> 使用 `Bun.spawn` 或 `Bun.spawnSync` 创建子进程
## 创建进程（`Bun.spawn()`）
以字符串数组的形式提供命令。`Bun.spawn()` 的结果是一个 `Bun.Subprocess` 对象。
```ts theme={null}
const proc = Bun.spawn(["bun", "--version"]);
console.log(await proc.exited); // 0
```
`Bun.spawn` 的第二个参数是一个配置子进程的参数对象。
```ts theme={null}
const proc = Bun.spawn(["bun", "--version"], {
cwd: "./path/to/subdir", // 指定工作目录
env: { ...process.env, FOO: "bar" }, // 指定环境变量
onExit(proc, exitCode, signalCode, error) {
// 退出处理器
},
});
proc.pid; // 子进程的进程 ID
```
## 输入流
默认情况下，子进程的输入流是未定义的；通过 `stdin` 参数进行配置。
```ts theme={null}
const proc = Bun.spawn(["cat"], {
stdin: await fetch("https://raw.githubusercontent.com/oven-sh/bun/main/examples/hashing.js"),
});
const text = await proc.stdout.text();
console.log(text); // "const input = "hello world".repeat(400); ..."
```
| 值 | 描述 |
| ------------------------ | ------------------------ |
| `null` | **默认。** 不向子进程提供输入 |
| `"pipe"` | 返回一个 `FileSink` 用于快速增量写入 |
| `"inherit"` | 继承父进程的 `stdin` |
| `Bun.file()` | 从指定文件读取 |
| `TypedArray \| DataView` | 使用二进制缓冲区作为输入 |
| `Response` | 使用响应 `body` 作为输入 |
| `Request` | 使用请求 `body` 作为输入 |
| `ReadableStream` | 使用可读流作为输入 |
| `Blob` | 使用 Blob 作为输入 |
| `number` | 从具有给定文件描述符的文件读取 |
使用 `"pipe"`，父进程可以增量写入子进程的输入流。
```ts theme={null}
const proc = Bun.spawn(["cat"], {
stdin: "pipe", // 返回一个 FileSink 用于写入
});
// 入队字符串数据
proc.stdin.write("hello");
// 入队二进制数据
const enc = new TextEncoder();
proc.stdin.write(enc.encode(" world!"));
// 发送缓冲数据
proc.stdin.flush();
// 关闭输入流
proc.stdin.end();
```
将 `ReadableStream` 传递给 `stdin` 会将其数据直接管道传输到子进程的输入：
```ts theme={null}
const stream = new ReadableStream({
start(controller) {
controller.enqueue("Hello from ");
controller.enqueue("ReadableStream!");
controller.close();
},
});
const proc = Bun.spawn(["cat"], {
stdin: stream,
stdout: "pipe",
});
const output = await proc.stdout.text();
console.log(output); // "Hello from ReadableStream!"
```
## 输出流
从 `stdout` 和 `stderr` 属性读取子进程的输出。默认情况下，它们是 `ReadableStream` 的实例。
```ts theme={null}
const proc = Bun.spawn(["bun", "--version"]);
const text = await proc.stdout.text();
console.log(text); // => "1.3.3\n"
```
通过向 `stdout/stderr` 传递以下值之一来配置输出流：
| 值 | 描述 |
| ------------ | ---------------------------------------------------------------- |
| `"pipe"` | **`stdout` 的默认值。** 将输出管道传输到返回的 `Subprocess` 对象的 `ReadableStream` |
| `"inherit"` | **`stderr` 的默认值。** 继承自父进程 |
| `"ignore"` | 丢弃输出 |
| `Bun.file()` | 写入指定文件 |
| `number` | 写入具有给定文件描述符的文件 |
## 退出处理
使用 `onExit` 回调监听进程退出或被杀死的事件。
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
const proc = Bun.spawn(["bun", "--version"], {
onExit(proc, exitCode, signalCode, error) {
// 退出处理器
},
});
```
`exited` 属性是一个 `Promise`，在进程退出时 resolve。
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
const proc = Bun.spawn(["bun", "--version"]);
await proc.exited; // 进程退出时 resolve
proc.killed; // boolean — 进程是否被杀死？
proc.exitCode; // null | number
proc.signalCode; // null | "SIGABRT" | "SIGALRM" | ...
```
要杀死一个进程：
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
const proc = Bun.spawn(["bun", "--version"]);
proc.kill();
proc.killed; // true
proc.kill(15); // 指定信号代码
proc.kill("SIGTERM"); // 指定信号名称
```
父 `bun` 进程在所有子进程退出后才会终止。使用 `proc.unref()` 将子进程与父进程分离。
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
const proc = Bun.spawn(["bun", "--version"]);
proc.unref();
```
## 资源使用
进程退出后，`resourceUsage()` 会报告其资源使用情况：
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
const proc = Bun.spawn(["bun", "--version"]);
await proc.exited;
const usage = proc.resourceUsage();
console.log(`Max memory used: ${usage.maxRSS} bytes`);
console.log(`CPU time (user): ${usage.cpuTime.user} µs`);
console.log(`CPU time (system): ${usage.cpuTime.system} µs`);
```
## 使用 AbortSignal
您可以使用 `AbortSignal` 中止子进程：
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
const controller = new AbortController();
const { signal } = controller;
const proc = Bun.spawn({
cmd: ["sleep", "100"],
signal,
});
// 稍后，中止进程：
controller.abort();
```
## 使用 timeout 和 killSignal
设置 `timeout` 可以在指定毫秒数后终止子进程：
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
// 5 秒后杀死进程
const proc = Bun.spawn({
cmd: ["sleep", "10"],
timeout: 5000, // 5 秒，单位毫秒
});
await proc.exited; // 5 秒后 resolve
```
默认情况下，Bun 使用 `SIGTERM` 杀死超时进程。使用 `killSignal` 选项指定不同的信号：
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
// 5 秒后用 SIGKILL 杀死进程
const proc = Bun.spawn({
cmd: ["sleep", "10"],
timeout: 5000,
killSignal: "SIGKILL", // 可以是字符串名称或信号编号
});
```
`killSignal` 选项还控制在 AbortSignal 被中止时发送的信号。
## 使用 maxBuffer
对于 `Bun.spawnSync`，`maxBuffer` 限制进程在 Bun 杀死它之前可以发出的输出字节数：
```ts index.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
// 在 'yes' 发出超过 100 字节的输出后杀死它
const result = Bun.spawnSync({
cmd: ["yes"], // 或在 Windows 上使用 ["bun", "exec", "yes"]
maxBuffer: 100,
});
// 进程退出
```
Bun 在超过限制后立即停止读取，因此返回的输出只会超过 `maxBuffer` 一个读取的量，而不会超过进程在杀死信号到达之前设法写入的量。这与 Node.js 的行为一致。
## 进程间通信（IPC）
Bun 支持两个 `bun` 进程之间的直接进程间通信通道。要从生成的 Bun 子进程接收消息，请指定一个 `ipc` 处理器。
```ts parent.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
const child = Bun.spawn(["bun", "child.ts"], {
ipc(message) {
/**
* 从子进程接收的消息
**/
},
});
```
父进程通过返回的 `Subprocess` 实例上的 `.send()` 方法向子进程发送消息。`ipc` 处理器也会接收发送消息的子进程作为其第二个参数。
```ts parent.ts icon="https://mintcdn.com/span-inc/82N53aP7NFbaCVSl/icons/typescript.svg?fit=max&auto=format&n=82N53aP7NFbaCVSl&q=85&s=787d39d6a7d96d7f9540dc74344eba23" theme={null}
const childProc = Bun.spawn(["bun", "child.ts"], {
ipc(message, childProc) {
/**
* 从子进程接收的消息
**/
childProc.send("Respond to child");
},
});
childProc.send("I am your father"); // 父进程也可以向子进程发送消息
```
子进程使用 `process.send()` 向父进程发送消息，并使用 `process.on("message")` 接收消息。这与 Node.js 中 `child_process.fork()` 使用的 API 相同。
```ts child.ts theme={null}
process.send("Hello from child as string");
process.send({ message: "Hello from child as object" });
process.on("message", message => {
// 打印来自父进程的消息
console.log(message);
});
```
```ts child.ts theme={null}
// 发送字符串
process.send("Hello from child as string");
// 发送对象
process.send({ message: "Hello from child as object" });
```
`serialization` 选项控制两个进程之间的底层通信格式：
* `advanced`：（默认）消息使用 JSC `serialize` API 进行序列化，支持克隆 [`structuredClone` 支持的一切](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)。不支持传输对象所有权。
* `json`：消息使用 `JSON.stringify` 和 `JSON.parse` 进行序列化，不支持 `advanced` 那么多对象类型。
要从父进程断开 IPC 通道，请调用：
```ts theme={null}
childProc.disconnect();
```
### Bun 与 Node.js 之间的 IPC
要在 `bun` 进程和 Node.js 进程之间使用 IPC，请在 `Bun.spawn` 中设置 `serialization: "json"`。这是因为 Node.js 和 Bun 使用不同的 JavaScript 引擎和不同的对象序列化格式。
```js bun-node-ipc.js icon="file-code" theme={null}
if (typeof Bun !== "undefined") {
const prefix = `[bun ${process.versions.bun} 🐇]`;
const node = Bun.spawn({
cmd: ["node", __filename],
ipc({ message }) {
console.log(message);
node.send({ message: `${prefix} 👋 hey node` });
node.kill();
},
stdio: ["inherit", "inherit", "inherit"],
serialization: "json",
});
node.send({ message: `${prefix} 👋 hey node` });
} else {
const prefix = `[node ${process.version}]`;
process.on("message", ({ message }) => {
console.log(message);
process.send({ message: `${prefix} 👋 hey bun` });
});
}
```
***
## 终端（PTY）支持
对于交互式终端应用程序，请使用 `terminal` 选项来生成附加了伪终端（PTY）的子进程。子进程会看到一个真正的终端，从而支持彩色输出、光标移动和交互式提示。
```ts theme={null}
const proc = Bun.spawn(["bash"], {
terminal: {
cols: 80,
rows: 24,
data(terminal, data) {
// 当从终端接收到数据时调用
process.stdout.write(data);
},
},
});
// 写入终端
proc.terminal.write("echo hello\n");
// 等待进程退出
await proc.exited;
// 关闭终端
proc.terminal.close();
```
当提供 `terminal` 选项时：
* 子进程看到 `process.stdout.isTTY` 为 `true`
* `stdin`、`stdout` 和 `stderr` 都连接到终端
* `proc.stdin`、`proc.stdout` 和 `proc.stderr` 返回 `null` — 请改用终端
* 通过 `proc.terminal` 访问终端
### 终端选项
| 选项 | 描述 | 默认值 |
| ------- | --------------------------------------------------------------------------------------------- | ------------------ |
| `cols` | 列数 | `80` |
| `rows` | 行数 | `24` |
| `name` | PTY 配置的终端类型（使用 `env` 选项单独设置 `TERM` 环境变量） | `"xterm-256color"` |
| `data` | 接收到数据时的回调 `(terminal, data) => void` | — |
| `exit` | PTY 流关闭时（EOF 或错误）的回调。`exitCode` 是 PTY 生命周期状态（0=EOF，1=错误），而非子进程退出代码。使用 `proc.exited` 获取进程退出信息。 | — |
| `drain` | 准备好接收更多数据时的回调 `(terminal) => void` | — |
### 终端方法
`proc.terminal` 返回的 `Terminal` 对象有以下方法：
```ts theme={null}
// 向终端写入数据
proc.terminal.write("echo hello\n");
// 调整终端大小
proc.terminal.resize(120, 40);
// 设置原始模式（禁用行缓冲和回显）
proc.terminal.setRawMode(true);
// 终端打开时保持事件循环存活
proc.terminal.ref();
proc.terminal.unref();
// 关闭终端
proc.terminal.close();
```
### 可复用终端
要在同一个终端会话中顺序运行多个命令，可以独立创建一个终端并在多个子进程之间复用：
```ts theme={null}
await using terminal = new Bun.Terminal({
cols: 80,
rows: 24,
data(term, data) {
process.stdout.write(data);
},
});
// 生成第一个进程
const proc1 = Bun.spawn(["echo", "first"], { terminal });
await proc1.exited;
// 为另一个进程复用终端
const proc2 = Bun.spawn(["echo", "second"], { terminal });
await proc2.exited;
// 通过 `await using` 自动关闭终端
```
当传递现有的 `Terminal` 对象时：
* 终端可以在多次 spawn 中复用
* 您可以控制何时关闭终端
* `exit` 回调在调用 `terminal.close()` 时触发，而不是在每个子进程退出时
* 使用 `proc.exited` 检测单个子进程的退出
### 平台差异
`Bun.Terminal` 在 Linux 和 macOS 上使用 `openpty()`，在 Windows 上使用 ConPTY（`CreatePseudoConsole`）。核心行为——子进程看到 TTY、`write()` 到达子进程的 stdin、子进程输出到达 `data` 回调、`resize()` 更新子进程的视图——在所有平台上都是相同的。一些细节有所不同：
* **Windows 上没有 termios。** `inputFlags`、`outputFlags`、`localFlags` 和 `controlFlags` 始终读取为 `0`，设置它们无效。`setRawMode()` 会记录该标志但对子进程没有效果；子进程控制自己的控制台模式。
* **Windows 上没有子进程时不会回显。** 在 POSIX 上，即使没有附加进程，内核的行规程也会将 `write()` 输入回显到 `data` 回调。ConPTY 没有行规程；输入会被缓冲等待下一个读取者。如果需要回显，请启动一个会回显的进程。
* **ConPTY 会重新编码输出。** ConPTY 将子进程的输出渲染到虚拟屏幕，并发出描述结果的任何 VT 序列，因此 `data` 回调接收的转义序列在语义上等价，但字节不一定相同。颜色和文本被保留；光标定位和重置序列可能会被重新排序或合并。ConPTY 还会在任何子进程输出之前发出一个简短的 VT 初始化序列（`\x1b[?9001h\x1b[?1004h…`）。
* **在 Windows 上，输入的 `\r` 不会转换为 `\n`。** POSIX `ICRNL` 会将回车符映射为输入中的换行符；ConPTY 原样传递 `\r`。
* **在 ConPTY 下，子进程中的 `process.on('SIGWINCH')` 不会触发**，除非子进程以原始模式读取 stdin。`process.stdout.columns`/`rows` 在 `resize()` 后确实会更新。这是 libuv 的限制，影响所有基于 libuv 的子进程（包括 Node.js）。
* 在 Windows 11 24H2（内部版本 26100）之前的版本上，`terminal.close()` 可能不会及时终止仍在运行的子进程，因为在这些版本上 [`ClosePseudoConsole`](https://learn.microsoft.com/zh-cn/windows/console/closepseudoconsole) 会阻塞直到 conhost 将其输出通过管道刷新完毕。如果需要在子进程仍在运行时销毁，请先杀死附加的进程。
***
## 阻塞 API（`Bun.spawnSync()`）
`Bun.spawnSync` 是 `Bun.spawn` 的阻塞等价物。它支持相同的输入和参数，并返回一个 `SyncSubprocess` 对象，该对象在几个方面与 `Subprocess` 不同。
1. 它包含一个 `success` 属性，指示进程是否以零退出代码退出。
2. `stdout` 和 `stderr` 属性是 `Buffer` 的实例，而不是 `ReadableStream`。
3. 没有 `stdin` 属性。请使用 `Bun.spawn` 来增量写入子进程的输入流。
```ts theme={null}
const proc = Bun.spawnSync(["echo", "hello"]);
console.log(proc.stdout.toString());
// => "hello\n"
```
一般规则：异步的 `Bun.spawn` API 更适合 HTTP 服务器和应用程序，而 `Bun.spawnSync` 更适合构建命令行工具。
***
## 基准测试
⚡️ `Bun.spawn` 和 `Bun.spawnSync` 使用 [`posix_spawn(3)`](https://man7.org/linux/man-pages/man3/posix_spawn.3.html)。
Bun 的 `spawnSync` 创建进程的速度比 Node.js `child_process` 模块快 60%。
```bash terminal icon="terminal" theme={null}
bun spawn.mjs
```
```txt theme={null}
cpu: Apple M1 Max
runtime: bun 1.x (arm64-darwin)
benchmark time (avg) (min … max) p75 p99 p995
--------------------------------------------------------- -----------------------------
spawnSync echo hi 888.14 µs/iter (821.83 µs … 1.2 ms) 905.92 µs 1 ms 1.03 ms
```
```sh terminal icon="terminal" theme={null}
node spawn.node.mjs
```
```txt theme={null}
cpu: Apple M1 Max
runtime: node v18.9.1 (arm64-darwin)
benchmark time (avg) (min … max) p75 p99 p995
--------------------------------------------------------- -----------------------------
spawnSync echo hi 1.47 ms/iter (1.14 ms … 2.64 ms) 1.57 ms 2.37 ms 2.52 ms
```
***
## 参考
以下是 Spawn API 和类型的参考。实际类型具有复杂的泛型，可以根据传递给 `Bun.spawn` 和 `Bun.spawnSync` 的选项强类型化 `Subprocess` 流。有关完整细节，请参阅 [bun.d.ts](https://github.com/oven-sh/bun/blob/main/packages/bun-types/bun.d.ts)。
```ts 查看 TypeScript 定义 可展开 theme={null}
interface Bun {
spawn(command: string[], options?: SpawnOptions.OptionsObject): Subprocess;
spawnSync(command: string[], options?: SpawnOptions.OptionsObject): SyncSubprocess;
spawn(options: { cmd: string[] } & SpawnOptions.OptionsObject): Subprocess;
spawnSync(options: { cmd: string[] } & SpawnOptions.OptionsObject): SyncSubprocess;
}
namespace SpawnOptions {
interface OptionsObject {
cwd?: string;
env?: Record;
stdio?: [Writable, Readable, Readable];
stdin?: Writable;
stdout?: Readable;
stderr?: Readable;
onExit?(
subprocess: Subprocess,
exitCode: number | null,
signalCode: number | null,
error?: ErrorLike,
): void | Promise;
ipc?(message: any, subprocess: Subprocess): void;
serialization?: "json" | "advanced";
windowsHide?: boolean;
windowsVerbatimArguments?: boolean;
argv0?: string;
signal?: AbortSignal;
timeout?: number;
killSignal?: string | number;
maxBuffer?: number;
terminal?: TerminalOptions; // PTY (POSIX) / ConPTY (Windows) 支持
}
type Readable =
| "pipe"
| "inherit"
| "ignore"
| null // 等同于 "ignore"
| undefined // 使用默认值
| BunFile
| ArrayBufferView
| number;
type Writable =
| "pipe"
| "inherit"
| "ignore"
| null // 等同于 "ignore"
| undefined // 使用默认值
| BunFile
| ArrayBufferView
| number
| ReadableStream
| Blob
| Response
| Request;
}
interface Subprocess extends AsyncDisposable {
readonly stdin: FileSink | number | undefined | null;
readonly stdout: ReadableStream> | number | undefined | null;
readonly stderr: ReadableStream> | number | undefined | null;
readonly readable: ReadableStream> | number | undefined | null;
readonly terminal: Terminal | undefined;
readonly pid: number;
readonly exited: Promise;
readonly exitCode: number | null;
readonly signalCode: NodeJS.Signals | null;
readonly killed: boolean;
kill(exitCode?: number | NodeJS.Signals): void;
ref(): void;
unref(): void;
send(message: any): void;
disconnect(): void;
resourceUsage(): ResourceUsage | undefined;
}
interface SyncSubprocess {
stdout: Buffer | undefined;
stderr: Buffer | undefined;
exitCode: number;
success: boolean;
resourceUsage: ResourceUsage;
signalCode?: string;
exitedDueToTimeout?: true;
pid: number;
}
interface TerminalOptions {
cols?: number;
rows?: number;
name?: string;
data?: (terminal: Terminal, data: Uint8Array) => void;
/** PTY 流关闭时调用（EOF 或错误）。exitCode 是 PTY 生命周期状态（0=EOF，1=错误），非子进程退出代码。 */
exit?: (terminal: Terminal, exitCode: number, signal: string | null) => void;
drain?: (terminal: Terminal) => void;
}
interface Terminal extends AsyncDisposable {
readonly closed: boolean;
write(data: string | BufferSource): number;
resize(cols: number, rows: number): void;
setRawMode(enabled: boolean): void;
ref(): void;
unref(): void;
close(): void;
}
interface ResourceUsage {
contextSwitches: {
voluntary: number;
involuntary: number;
};
cpuTime: {
user: number;
system: number;
total: number;
};
maxRSS: number;
messages: {
sent: number;
received: number;
};
ops: {
in: number;
out: number;
};
shmSize: number;
signalCount: number;
swapCount: number;
}
type Signal =
| "SIGABRT"
| "SIGALRM"
| "SIGBUS"
| "SIGCHLD"
| "SIGCONT"
| "SIGFPE"
| "SIGHUP"
| "SIGILL"
| "SIGINT"
| "SIGIO"
| "SIGIOT"
| "SIGKILL"
| "SIGPIPE"
| "SIGPOLL"
| "SIGPROF"
| "SIGPWR"
| "SIGQUIT"
| "SIGSEGV"
| "SIGSTKFLT"
| "SIGSTOP"
| "SIGSYS"
| "SIGTERM"
| "SIGTRAP"
| "SIGTSTP"
| "SIGTTIN"
| "SIGTTOU"
| "SIGUNUSED"
| "SIGURG"
| "SIGUSR1"
| "SIGUSR2"
| "SIGVTALRM"
| "SIGWINCH"
| "SIGXCPU"
| "SIGXFSZ"
| "SIGBREAK"
| "SIGLOST"
| "SIGINFO";
```