# @ariestools/cli-kit-yargs 中文文档

规范地址：https://npmcn.com/package/%40ariestools/cli-kit-yargs/

版本：2\.1\.0
npm 元数据更新时间：2026-10-06T23:42:25.954Z
中文译文更新时间：2026-11-06T19:10:55.441Z
软件包许可：LGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40ariestools/cli-kit-yargs
原文对照：https://npmcn.com/package/%40ariestools/cli-kit-yargs/?lang=original
项目主页：https://ariestools.ai/
源码仓库：https://github.com/ariestools/cli-kit

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

- 包体积（解压后）：113 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26
- 运行依赖：2 个
- peer 依赖：yargs ^18\.2
- 首次发布：2026-07-21T16:01:16.621Z
- 最新版本发布：2026-10-06T23:42:25.754Z
- 近 30 天下载量：2655（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

用于可重复使用的演员命令行应用程序的 Yargs 适配器

## 安装

```sh
npm install @ariestools/cli-kit-yargs
```

也可以使用：`pnpm add @ariestools/cli-kit-yargs`、`yarn add @ariestools/cli-kit-yargs`、`bun add @ariestools/cli-kit-yargs`

## README

# @ riestools/cli- kit- yargs (英语)

用于可再使用的演员命令行应用程序的 Yargs 适配器.

包里没有雅格斯 `@ariestools/cli-kit` 而路由解析器帮助,版本,验证错误,同步失败,并通过核心退出 `ProcessHost` 边界。 这使得一个被配置的CLI安全地与录音主机一起锻炼,而不是让雅格斯写到环境控制台或终止测试过程.

帮助,版本,和完成输出 仍然结束运行的方式 Yargs自己的进程退出。 通过主机行走意味着Yargs不再结束过程;它记录出口并持续进行. 所以一旦Yargs离开0, `runYargsApplication` 跳过在解析器上注册的每一个中间软件,包括 `.check()` 召回电话。 一个根 `--help`, (中文(简体) ), `-h`,或裸体 `help` 因此,从未到达应用程序的配置中间软件,以及 `app bogus --help` 打印帮助而不是 `Unknown command: bogus`。根帮助也等待动脉 `$0` 构建者:亚格斯打印,只有在构建者和解后才会有所帮助,否则就是在解剖完成后. 未知命令失败在保留使用输出和失败映射的同时, 停止后期的中间件和匹配的处理器; 见 [拒绝未知命令](https://npmcn.com/package/%40ariestools/cli-kit-yargs/#readme-rejecting-unknown-commands)。 。 。 .

`runYargsApplication` 接受可选选项 `mapFailureToExitCode` 映射器既适用于解析器也适用于处理器故障:映射器收到故障源(`'parse'` 对于验证失败, `'handler'` 用于处理器或中间软件拒绝,返回一个数字,选择退出代码, `undefined` 保留默认退出代码一。 投出,或返回整数范围0–255以外的代码的映射器会倒回退出代码一. 故意行为 `ProcessExitError` 出口通过无动于衷.

根帮助使用 Yargs 的承诺返回 `getHelp()` 它的回调输出 路径。 拒绝同步 `$0` 建构者通过现有的 处理器- 失败边界: 没有成功帮助输出或命令效果, 1 `onFailure` 调用,原始错误会传递给映射器。 成功 帮助仍然等待建设者,未使用的默认建设者仍然懒惰. 两个中间软件阶段都等待等待帮助,然后决定是否运行. 明确字符串/ 默认 `showHelp` 超载保留了本地的Yargs行为.

失败的输出范围是同一来源。 A 类 **剖析来源** 失败( Yargs 验证或使用错误,包括由 `rejectUnknownCommands`)仍然打印用法/帮助块,因为呼叫者错误地输入了CLI. A 类 **处理器来源** 失败( 丢弃的命令处理器或中间软件—— 例如映射出一个退出的配置错误) `78`将原始错误打印为 stderr, 包括它的堆栈当存在时, 没有用法堆放 。 生产保持了完整的诊断,因此致命的处理器故障仍然可以诊断;只有吵闹的用法被压制. 退出代码和 `mapFailureToExitCode` 合同不变;只有原产地的印刷品不同.

## 重复选项

`configureCliSurface` 对每个消费者实行一种重复政策 `withRepeatableOptions(parser)` 对组装的解析器适用同样的政策:

-   已声明选项 `array: true` 编号 : `type: 'array'` 收集每起事件(`--tag a --tag b` 给 `['a', 'b']`),并具有可变位置(`serve [files..]`保持每个值;
-   已声明选项 `nargs: n` 与 `n > 1` 保留最后的 `n` 数值;
-   每一个其他宣布的选项都会在其所有拼写下解决最后的胜负——别名,骆驼Case和连字符键,点键——所以 `--out a --out b` 手握处理器 `'b'` 而不是数组.

保险单保留了 Yargs 的默认 `duplicate-arguments-array: true` 并恢复在验证前的中间软件中的最后胜利,所以 `choices`, (中文(简体) ), `.check(...)`, (中文(简体) ), `coerce`,处理器只看到存活值: `--mode bogus --mode safe` 通过 `choices: ['fast', 'safe']`,以及 `--mode safe --mode bogus` 失败了。 转动 `duplicate-arguments-array` 关闭在 args 18 下不能替代 : 它只保留一个数组选项的最后一次出现, 将一个变量位置切换到其最后一个值, 并且可以留下一个数组选项的骆驼 大小写密钥不同意其连字符密钥.

```ts
import { runYargsApplication, withRepeatableOptions } from '@ariestools/cli-kit-yargs'

await runYargsApplication({
  host,
  configure: parser => withRepeatableOptions(parser.scriptName('app'))
    .command(serveCommand)
    .strictOptions()
    .help(),
})
```

三个制约因素使政策保持不变:

-   离开 `duplicate-arguments-array` 未设置于任意 `.parserConfiguration(...)` 电话,包括一个在a `configureCliSurface` `customize` 钩. 这个调用取代了 Yargs 的配置批发, 一个未设置的密钥保持了 Yargs 的默认 `true`· ; `withRepeatableOptions` 永远不要调用它,所以它不能丢弃之前应用的设置 .
-   应用 `withRepeatableOptions` 在宣布任何选项之前 `coerce`: yargs在注册顺序中作为中间软件运行强制函数,所以一个注册较早的收到未被拼接的数组.
-   宣布一个变相立场 `.positional(...)`,将其记录为数组选项(`.strictOptions()` 拒绝未申报的立场。 仅通过命名 `.coerce(...)` 或非阵型 `.option(...)` 声明一个单值选项,其值崩溃到最后一个值.

## 拒绝未知命令

`.strictCommands()` 无法标记未知的命令一次 `$0` 默认命令是注册的——默认命令作为位置消耗出出错的符号,雅格斯默默接受. `rejectUnknownCommands(parser, commands)` 以 `.check()` 比较每个剩余位置与命令名称(和别名) `commands`,扔出一个解析来源 `Unknown command: <token>` 任何未确认的东西 赤裸裸的引用, 注册命令及其选项 `help`编号 :`$0` 路径没有变化。 在每个之后应用 `.command(...)` 登记和登记前 `.help()`,通过您注册的相同数组:

```ts
import { rejectUnknownCommands, runYargsApplication } from '@ariestools/cli-kit-yargs'

await runYargsApplication({
  host,
  mapFailureToExitCode: (_error, origin) => (origin === 'parse' ? 64 : undefined),
  configure: (parser) => {
    let configured = parser.scriptName('app')
    for (const command of commands) configured = configured.command(command)
    return rejectUnknownCommands(configured, commands).help().version(version)
  },
})
```

无论运行时间类型如何,检查所有非空的剩余标志。 弧线类型 `argv._` 作为 `(string | number)[]` 并且,由于默认 `parse-positional-numbers` 启用后,就强制给联署材料号码一个赤裸的数字符号 `app 0`, (中文(简体) ), `app 123`,以及 `app -5` 标记为 `Unknown command: 0` (等)一一如来相. 没有 `.parserConfiguration({ 'parse-positional-numbers': false })` 需要绕道去抓一个数字迷路的人。 信息重复了被胁迫的价值,而不是原始文本,所以一个异国情调的字面规范化了—— `1e3` 读取 `Unknown command: 1000`, (中文(简体) ), `0x10` 读取 `16`, (中文(简体) ), `1.50` 读取 `1.5` 因为Yargs已经胁迫了我们 `.check()` 运行。 拒绝在每一种情况下都是正确的;只有重复的文本不同。 空符号( A)`app ""`)是排除的一条:它没有命令的名称,而掉到 `$0`。 。 。 .

四个制约因素使检查准确无误.

-   这个 `commands` 数组必须等同在解析器上注册的集——被接受的名称集是从中衍生出来的,而不是从解析器上读回,所以任何漂移都无声地拒绝一个有效的命令或接受一个未处理的命令.
-   每个被接受的位置必须在其命令字符串中宣布(`serve <file>`, (中文(简体) ), `serve [file]`, (中文(简体) ), `serve [files..]`: Yargs 消耗已申报位置 `argv._` 在检查运行前输入已命名的密钥——包括数值值的密钥,所以 `serve <port>` 引用为 `serve 8080` 但是,如果命令读取了它从未宣布过的临时性位置,那么它们就会留在 `argv._` 将第一个被拒绝者视为 `Unknown command: <value>`。 。 。 .
-   在父命令中注册的子命令 `builder` 也必须出现在 `commands`雅格士留下两个符号 `argv._` (单位:千美元)`db migrate` 产量 `['db', 'migrate']`),因此,在数组中缺失的嵌入式名称被拒绝为 `Unknown command: migrate`。将嵌入式模块与顶层模块一起通过,以一个被接受的平面名称集为代价,确定:然后在顶层也接受嵌入式名称,从顶端到顶端 `$0`。 。 。 .
-   后键 `--` 分隔符不会通过, 除非呼叫器允许 `.parserConfiguration({ 'populate--': true })`叶子叶 `populate--` 默认关闭, 将这些符号合并为 `argv._` 而不是说 `argv['--']`这样 `app local -- raw` 以 `Unknown command: raw` (和 `app local -- 5` 作为 `Unknown command: 5`) (中文(简体) ). 启用 `populate--` 引导他们到 `argv['--']`页:1 `argv._` 和这个检查的伸手.

当使用通过 `runYargsApplication`,一个未知的键盘检查稍后停止 中间软件和匹配的处理器:既不是 `$0` 赤裸的流浪者管理者 也没有 `publish` 处理器 `app publish 0` 执行。 用法输出, 剖析出源映射,默认出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出 保持原状 在拒绝检查前运行的中间软件和构建器 保留现有的执行命令。 这项担保属于适配器; 使用独立的 Yargs 解析调用程序必须提供等效 失败 - 退出行为本身。 上面的平面接受姓名限制 保持不变.

使用 `environmentToYargsConfig` 当应用程序拥有配置文件加载并想要替换 Yargs 进程时 - global `.env()` 以明确提供的环境进行检索。 由此而来平平的被点对象维护了雅格斯环境的关键正常化,并可以传递到 `.config()` 解析前 :

```ts
import { createNodeProcessHostWithDotEnv } from '@ariestools/cli-kit-node'
import { environmentToYargsConfig, runYargsApplication } from '@ariestools/cli-kit-yargs'

const host = createNodeProcessHostWithDotEnv()

await runYargsApplication({
  host,
  configure: parser => parser
    .option('port', { type: 'number' })
    .config(environmentToYargsConfig(host.environment, 'XL1', { allowedKeys: ['port'] }))
    .scriptName('xl1')
    .command(commands)
    .strictOptions()
    .help()
    .version(version),
})
```

装入 dotenv 文件通过 `@ariestools/cli-kit-node` (单位:千美元)`loadDotEnvFile` 编号 : `createNodeProcessHostWithDotEnv`)所以数值达到 `host.environment` 不发生变异 `process.env`。这种转换保留了命令线上环境优先级,但它不是Yargs-native配置文件选项的一般替代: Yargs 将配置对象排在配置文件下方, 并处理顶级 `extends` 键。 此类申请应先解决这些优先和保留关键规则,然后将标的送交 `.config()`。 。 。 .

使用严格的选项,保持环境许可清单的明确性,并在其名称中标明 映射形式( e)`port`, (中文(简体) ), `rpcUrl`) (中文(简体) ). 实例声明 `port` 全球,所以 配置对每个命令都是有效的 。 当命令接受不同的选项时, 声明选项和呼叫 `configureCommandEnvironment` 在每个选中的内 叶相生者. 帮助此边界需要允许列表; 独立 转换器保留其可选许可列表。 A 类 `serve` 构建者可以允许 `port` 时 (单位:千美元) `status` 允许构建器 `format`数字 :

```ts
import { configureCommandEnvironment, configureCliSurface, runYargsApplication } from '@ariestools/cli-kit-yargs'

const commandEnvironment = { environment: host.environment, prefix: 'APP_' }
const commands = [
  {
    command: ['serve', 'run'],
    builder: parser => configureCommandEnvironment(
      parser.option('port', { alias: 'p', type: 'number' }),
      { ...commandEnvironment, allowedKeys: ['port'] },
    ),
    handler: argv => serve(argv.port),
  },
  {
    command: 'status',
    builder: parser => configureCommandEnvironment(
      parser.option('format', { choices: ['json', 'text'], type: 'string' }),
      { ...commandEnvironment, allowedKeys: ['format'] },
    ),
    handler: argv => status(argv.format),
  },
]

await runYargsApplication({
  host,
  configure: parser => configureCliSurface(parser, {
    commands, host, scriptName: 'app', usage: 'app <command>', version,
  }),
})
```

`APP_PORT=8080 APP_FORMAT=json app serve` 只接收 `port`· ; `app status` 只接收 `format`。 。 。 . `app run -p 9090` 覆盖 `APP_PORT`,以及 `app serve --format json` 仍然失败 。 包含共享 当叶子接受它们时,每片叶子的允许列表中的全局键。 为了筑巢 命令,在叶子建构器内应用此助手,而不是父的 构建者:父配置对象由每个孩子继承.

无关联的前缀变量和其他命令的密钥被过滤. 保持打错的 CLI 旗帜严格. root-parser 选项无法导出反演 这个浮出水面,在懒惰的建设者运行之前。 过滤删除不支持 环境值; 仅使用配置字段的应用程序需要一个单独的 配置管道或明确宣布的选项。 通用转换器保存 其针对有意接受所有钥匙的消费者的可选许可列表。 现有 `configureCliSurface.environmentConfig` 仍然是根/全球配置路径 不推断或过滤特定命令的密钥。 它的召唤者只能保留 全球公布的密钥。 帮助者不会更改 Yargs 配置文件优先级 或对保留最高层的特殊解释 `extends` 键.

Mapped dotted keys保留了Yargs自己的严格验证规则. 随着它的默认 标记, 只声明 `api.port` 仍然产生一个 `api` 集装箱 严格选项可以拒绝为未知。 平平点选项表面可以使用 `.parserConfiguration({ 'dot-notation': false })` 并宣布 `api.port` 当然 将任意嵌入的应用程序配置保留在单独的区域 配置管道,而不是把它当作CLI选项的联盟.

## 许可证

LGPL-3.0 仅限

## 常见问题

### @ariestools/cli-kit-yargs 是什么？

用于可重复使用的演员命令行应用程序的 Yargs 适配器

### 如何安装 @ariestools/cli-kit-yargs？

在项目目录运行 npm install @ariestools/cli-kit-yargs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：yargs（^18\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ariestools/cli-kit-yargs 支持 TypeScript 吗？

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

### @ariestools/cli-kit-yargs 支持 ESM 还是 CommonJS？

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

### @ariestools/cli-kit-yargs 需要什么版本的 Node\.js？

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

### @ariestools/cli-kit-yargs 可以商用吗？

@ariestools/cli-kit-yargs 使用 LGPL-3\.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @ariestools/cli-kit-yargs 的下载量有多少？

根据 npm 官方下载统计，@ariestools/cli-kit-yargs 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,655 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ariestools/cli-kit-yargs 还在维护吗？

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