# tinyexec 中文文档

规范地址：https://npmcn.com/package/tinyexec/

版本：1\.3\.1
npm 元数据更新时间：2026-09-03T08:50:07.571Z
中文译文更新时间：2026-11-04T19:32:20.457Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/tinyexec
原文对照：https://npmcn.com/package/tinyexec/?lang=original
项目主页：https://github.com/tinylibs/tinyexec#readme
源码仓库：https://github.com/tinylibs/tinyexec

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：27 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2024-07-01T20:58:48.190Z
- 最新版本发布：2026-09-03T08:50:07.324Z
- 近 30 天下载量：665890491（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 12 个）

## 中文简介

用于在Node中执行进程的最小库

## 安装

```sh
npm install tinyexec
```

也可以使用：`pnpm add tinyexec`、`yarn add tinyexec`、`bun add tinyexec`

## README

# tinyexec📟

> 用于执行命令的最小包

创建这个包是为了提供与child交互的最小方式 无需手动处理流、管道等的进程。

## 安装

```sh
$ npm i -S tinyexec
```

## 用法

一个进程可以像这样被生成和等待：

```ts
import {x} from 'tinyexec';

const result = await x('ls', ['-l']);

// result.stdout - the stdout as a string
// result.stderr - the stderr as a string
// result.exitCode - the process exit code as a number
```

默认情况下，tinyexec不会抛出非零退出码。检查 `result.exitCode` 或通过 `{throwOnError: true}`。

输出完全按照生成的方式返回；尾随换行符不会被修剪。如果你需要修剪，明确地做：

```ts
const clean = result.stdout.replace(/\r?\n$/, '');
```

你也可以通过异步循环遍历输出的行：

```ts
import {x} from 'tinyexec';

const proc = x('ls', ['-l']);

for await (const line of proc) {
  // line will be from stderr/stdout in the order you'd see it in a term
}
```

### 选项

可以通过传递选项来更好地控制进程的生成：

```ts
await x('ls', [], {
  timeout: 1000
});
```

options对象可以有以下属性：

-   `signal` ——一个 `AbortSignal` 允许中止执行
-   `timeout` 强制终止进程的时间（以毫秒为单位）
-   `persist` ——如果 `true`，该进程将在主机退出后继续
-   `stdin` - `string` 或另一个 `Result` 这将被用作流程的输入
-   `nodeOptions` -任何有效的选项到节点的底层 `spawn` 函数
-   `throwOnError` -如果为true，非零退出码将抛出错误
-   `nodePath` ——如果 `false`， `node_modules/.bin` 目录和当前节点可执行文件的目录将不会被附加到 `PATH` (默认为 `true`）

### 将字符串传递给stdin

你可以传递一个字符串给 `stdin`，这对于空白敏感值和不应该在shell历史记录中暴露的秘密非常有用：

```ts
const result = await x('gh', ['auth', 'login', '--with-token'], {
  stdin: process.env.GITHUB_TOKEN
});

console.log(result.exitCode);
```

### 管道连接到另一个进程

可以将一个进程管道到另一个进程 `pipe` 方法:

```ts
const proc1 = x('ls', ['-l']);
const proc2 = proc1.pipe('grep', ['.js']);
const result = await proc2;

console.log(result.stdout);
```

`pipe` 采用与常规执行相同的选项。例如，你可以 将超时传递给管道调用：

```ts
proc1.pipe('grep', ['.js'], {
  timeout: 2000
});
```

### 终止进程

你可以通过 `kill` 方法:

```ts
const proc = x('ls');

proc.kill();

// or with a signal
proc.kill('SIGHUP');
```

### 节点模块/二进制文件

默认情况下，节点的可用二进制文件 `node_modules` 将是可访问的 在你的指挥下。

例如，在回购中 `eslint` 安装:

```ts
await x('eslint', ['.']);
```

在这个例子中， `eslint` 会来自本地安装吗 `node_modules`。

如果你不愿意的话 `node_modules/.bin` (或目录的当前 `node` 可执行的)附加到 `PATH`,通过 `nodePath: false`：

```ts
await x('eslint', ['.'], {nodePath: false});
```

### 使用中止信号

可以将中止信号传递给进程，以便稍后中止该进程 时间。这将导致进程被终止并 `aborted` 被设置 来 `true`。

```ts
const aborter = new AbortController();
const proc = x('node', ['./foo.mjs'], {
  signal: aborter.signal
});

// elsewhere...
aborter.abort();

await proc;

proc.aborted; // true
proc.killed; // true
```

### 使用命令字符串

如果您需要继续以字符串形式支持命令(例如：“command arg0 arg1”)， 你可以用 [args-tokenizer](https://github.com/TrySound/args-tokenizer)， 用于将shell命令字符串解析为数组的轻量级库。

```ts
import {x} from 'tinyexec';
import {tokenizeArgs} from 'args-tokenizer';

const commandString = 'echo "Hello, World!"';
const [command, ...args] = tokenizeArgs(commandString);
const result = await x(command, args);

result.stdout; // Hello, World!
```

### 同步

你可以用 `xSync` 对于同步（阻塞）执行：

```ts
import {xSync} from 'tinyexec';

const result = xSync('ls', ['-l']);

// result.stdout - the stdout as a string
// result.stderr - the stderr as a string
// result.exitCode - the process exit code as a number
```

像异步API一样，你可以遍历行：

```ts
const result = xSync('ls', ['-l']);

for (const line of result) {
  // line will be from stdout then stderr
}
```

由于同步API阻塞了事件循环，所以异步API中支持的一些特性是同步API不支持的：

-   `signal`
-   `persist`
-   `kill()` 方法
-   `stdin` 管道
-   `pipe()` 方法

其他选项如 `timeout`， `throwOnError`, `nodeOptions` 以同样的方式工作。

## API

调用 `x(command[, args])` 返回一个可等待对象 `Result` 它有 以下API方法和属性可用：

### `pipe(command[, args[, options]])`

将当前命令传输到另一个命令。例如:

```ts
x('ls', ['-l'])
  .pipe('grep', ['js']);
```

参数说明如下：

-   `command` -要执行的命令(_没有任何争论_）
-   `args` -参数数组
-   `options` - options对象

### `process`

底层的Node.js `ChildProcess`． Tinyexec保持表面最小化，并且不重新暴露每个child\_process方法/事件。使用 `proc.process` 用于高级访问（流、事件等）。

```ts
const proc = x('node', ['./foo.mjs']);

proc.process?.stdout?.on('data', (chunk) => {
  // ...
});
proc.process?.once('close', (code) => {
  // ...
});
```

### `kill([signal])`

用指定的信号终止当前进程。默认情况下，这将 使用 `SIGTERM` 信号。

例如:

```ts
const proc = x('ls');

proc.kill();
```

### `pid`

当前进程ID。例如:

```ts
const proc = x('ls');

proc.pid; // number
```

### `aborted`

进程是否已中止(通过 `signal` 最初 传入options对象)。

例如:

```ts
const proc = x('ls');

proc.aborted; // bool
```

### `killed`

进程是否已被终止(例如通过 `kill()` 或者中止 信号)。

例如:

```ts
const proc = x('ls');

proc.killed; // bool
```

### `exitCode`

进程完成执行时收到的退出代码。

例如:

```ts
const proc = x('ls');

proc.exitCode; // number (e.g. 1)
```

## 与其他库的比较

`tinyexec` 目的是在Node自己的层之上提供一个轻量级的层 `child_process` API。

与其他库相比，一些明显的好处是 `tinyexec` 会轻多少，有多少 占用空间更小，接口更抽象（更“神奇”）。它 还会有同等的安全性和跨平台支持来普及吗 替代方案。

有许多其他库不可能包含的特性 要实现，因为它们会阻止我们提供轻量级层。

例如，如果您喜欢编写脚本而不是单独的命令，那么 更喜欢使用模板，我们强烈推荐 [zx](https://github.com/google/zx)． Zx是一个更高级的库 一些相同的工作吗 `tinyexec` 但是在模板字符串后面吗 接口。

类似地，像 `execa` 会为各种事情提供帮手吗 比如将文件作为输入传递给进程。我们选择不支持以下功能 这是因为它们中的许多很容易自己完成（使用Node自己的api）。

## 常见问题

### tinyexec 是什么？

用于在Node中执行进程的最小库

### 如何安装 tinyexec？

在项目目录运行 npm install tinyexec，或使用 pnpm add / yarn add / bun add。

### tinyexec 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### tinyexec 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### tinyexec 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### tinyexec 可以商用吗？

tinyexec 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### tinyexec 的下载量有多少？

根据 npm 官方下载统计，tinyexec 在 2026/10/05 – 2026/11/03 这 30 天内被下载 665,890,491 次，日均约 22,196,350 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### tinyexec 还在维护吗？

最新版本 1\.3\.1 发布于 2026/09/03（2 个月前）；至今共发布 26 个版本，其中过去 12 个月发布了 12 个；首次发布于 2024/07/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。