Spawn

创建进程（`Bun.spawn()`）

以字符串数组的形式提供命令。Bun.spawn() 的结果是一个 Bun.Subprocess 对象。

const proc = Bun.spawn(["bun", "--version"]);
console.log(await proc.exited); // 0

Bun.spawn 的第二个参数是一个配置子进程的参数对象。

const proc = Bun.spawn(["bun", "--version"], {
  cwd: "./path/to/subdir", // 指定工作目录
  env: { ...process.env, FOO: "bar" }, // 指定环境变量
  onExit(proc, exitCode, signalCode, error) {
    // 退出处理器
  },
});

proc.pid; // 子进程的进程 ID

输入流

默认情况下，子进程的输入流是未定义的；通过 stdin 参数进行配置。

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"，父进程可以增量写入子进程的输入流。

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 会将其数据直接管道传输到子进程的输入：

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 的实例。

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 回调监听进程退出或被杀死的事件。

index.ts

const proc = Bun.spawn(["bun", "--version"], {
  onExit(proc, exitCode, signalCode, error) {
    // 退出处理器
  },
});

exited 属性是一个 Promise，在进程退出时 resolve。

index.ts

const proc = Bun.spawn(["bun", "--version"]);

await proc.exited; // 进程退出时 resolve
proc.killed; // boolean — 进程是否被杀死？
proc.exitCode; // null | number
proc.signalCode; // null | "SIGABRT" | "SIGALRM" | ...

要杀死一个进程：

index.ts

const proc = Bun.spawn(["bun", "--version"]);
proc.kill();
proc.killed; // true

proc.kill(15); // 指定信号代码
proc.kill("SIGTERM"); // 指定信号名称

父 bun 进程在所有子进程退出后才会终止。使用 proc.unref() 将子进程与父进程分离。

index.ts

const proc = Bun.spawn(["bun", "--version"]);
proc.unref();

资源使用

进程退出后，resourceUsage() 会报告其资源使用情况：

index.ts

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 中止子进程：

index.ts

const controller = new AbortController();
const { signal } = controller;

const proc = Bun.spawn({
  cmd: ["sleep", "100"],
  signal,
});

// 稍后，中止进程：
controller.abort();

使用 timeout 和 killSignal

设置 timeout 可以在指定毫秒数后终止子进程：

index.ts

// 5 秒后杀死进程
const proc = Bun.spawn({
  cmd: ["sleep", "10"],
  timeout: 5000, // 5 秒，单位毫秒
});

await proc.exited; // 5 秒后 resolve

默认情况下，Bun 使用 SIGTERM 杀死超时进程。使用 killSignal 选项指定不同的信号：

index.ts

// 5 秒后用 SIGKILL 杀死进程
const proc = Bun.spawn({
  cmd: ["sleep", "10"],
  timeout: 5000,
  killSignal: "SIGKILL", // 可以是字符串名称或信号编号
});

killSignal 选项还控制在 AbortSignal 被中止时发送的信号。

使用 maxBuffer

对于 Bun.spawnSync，maxBuffer 限制进程在 Bun 杀死它之前可以发出的输出字节数：

index.ts

// 在 'yes' 发出超过 100 字节的输出后杀死它
const result = Bun.spawnSync({
  cmd: ["yes"], // 或在 Windows 上使用 ["bun", "exec", "yes"]
  maxBuffer: 100,
});
// 进程退出

Bun 在超过限制后立即停止读取，因此返回的输出只会超过 maxBuffer 一个读取的量，而不会超过进程在杀死信号到达之前设法写入的量。这与 Node.js 的行为一致。

进程间通信（IPC）

Bun 支持两个 bun 进程之间的直接进程间通信通道。要从生成的 Bun 子进程接收消息，请指定一个 ipc 处理器。

parent.ts

const child = Bun.spawn(["bun", "child.ts"], {
  ipc(message) {
    /**
     * 从子进程接收的消息
     **/
  },
});

父进程通过返回的 Subprocess 实例上的 .send() 方法向子进程发送消息。ipc 处理器也会接收发送消息的子进程作为其第二个参数。

parent.ts

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 相同。

child.ts

process.send("Hello from child as string");
process.send({ message: "Hello from child as object" });

process.on("message", message => {
  // 打印来自父进程的消息
  console.log(message);
});

child.ts

// 发送字符串
process.send("Hello from child as string");

// 发送对象
process.send({ message: "Hello from child as object" });

serialization 选项控制两个进程之间的底层通信格式：

advanced：（默认）消息使用 JSC serialize API 进行序列化，支持克隆 structuredClone 支持的一切。不支持传输对象所有权。
json：消息使用 JSON.stringify 和 JSON.parse 进行序列化，不支持 advanced 那么多对象类型。

要从父进程断开 IPC 通道，请调用：

childProc.disconnect();

Bun 与 Node.js 之间的 IPC

要在 bun 进程和 Node.js 进程之间使用 IPC，请在 Bun.spawn 中设置 serialization: "json"。这是因为 Node.js 和 Bun 使用不同的 JavaScript 引擎和不同的对象序列化格式。

bun-node-ipc.js

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）的子进程。子进程会看到一个真正的终端，从而支持彩色输出、光标移动和交互式提示。

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 对象有以下方法：

// 向终端写入数据
proc.terminal.write("echo hello\n");

// 调整终端大小
proc.terminal.resize(120, 40);

// 设置原始模式（禁用行缓冲和回显）
proc.terminal.setRawMode(true);

// 终端打开时保持事件循环存活
proc.terminal.ref();
proc.terminal.unref();

// 关闭终端
proc.terminal.close();

可复用终端

要在同一个终端会话中顺序运行多个命令，可以独立创建一个终端并在多个子进程之间复用：

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 会阻塞直到 conhost 将其输出通过管道刷新完毕。如果需要在子进程仍在运行时销毁，请先杀死附加的进程。

阻塞 API（`Bun.spawnSync()`）

Bun.spawnSync 是 Bun.spawn 的阻塞等价物。它支持相同的输入和参数，并返回一个 SyncSubprocess 对象，该对象在几个方面与 Subprocess 不同。

它包含一个 success 属性，指示进程是否以零退出代码退出。
stdout 和 stderr 属性是 Buffer 的实例，而不是 ReadableStream。
没有 stdin 属性。请使用 Bun.spawn 来增量写入子进程的输入流。

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)。

Bun 的 spawnSync 创建进程的速度比 Node.js child_process 模块快 60%。

terminal

bun spawn.mjs

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

terminal

node spawn.node.mjs

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。

查看 TypeScript 定义可展开

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<string, string | undefined>;
    stdio?: [Writable, Readable, Readable];
    stdin?: Writable;
    stdout?: Readable;
    stderr?: Readable;
    onExit?(
      subprocess: Subprocess,
      exitCode: number | null,
      signalCode: number | null,
      error?: ErrorLike,
    ): void | Promise<void>;
    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<Uint8Array<ArrayBuffer>> | number | undefined | null;
  readonly stderr: ReadableStream<Uint8Array<ArrayBuffer>> | number | undefined | null;
  readonly readable: ReadableStream<Uint8Array<ArrayBuffer>> | number | undefined | null;
  readonly terminal: Terminal | undefined;
  readonly pid: number;
  readonly exited: Promise<number>;
  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<ArrayBuffer>) => 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";

开始入门

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

互操作与工具

实用工具

标准与兼容性

贡献指南

创建进程（`Bun.spawn()`）

输入流

输出流

退出处理

资源使用

使用 AbortSignal

使用 timeout 和 killSignal

使用 maxBuffer

进程间通信（IPC）

Bun 与 Node.js 之间的 IPC

终端（PTY）支持

终端选项

终端方法

可复用终端

平台差异

阻塞 API（`Bun.spawnSync()`）

基准测试

参考

​创建进程（Bun.spawn()）

​输入流

​输出流

​退出处理

​资源使用

​使用 AbortSignal

​使用 timeout 和 killSignal

​使用 maxBuffer

​进程间通信（IPC）

​Bun 与 Node.js 之间的 IPC

​终端（PTY）支持

​终端选项

​终端方法

​可复用终端

​平台差异

​阻塞 API（Bun.spawnSync()）

​基准测试

​参考

创建进程（`Bun.spawn()`）

输入流

输出流

退出处理

资源使用

使用 AbortSignal

使用 timeout 和 killSignal

使用 maxBuffer

进程间通信（IPC）

Bun 与 Node.js 之间的 IPC

终端（PTY）支持

终端选项

终端方法

可复用终端

平台差异

阻塞 API（`Bun.spawnSync()`）

基准测试

参考