# @benev/argv 中文文档

规范地址：https://npmcn.com/package/%40benev/argv/

版本：0\.3\.14
npm 元数据更新时间：2026-02-21T05:39:00.237Z
中文译文更新时间：2026-11-07T22:16:25.067Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40benev/argv
原文对照：https://npmcn.com/package/%40benev/argv/?lang=original
项目主页：https://github.com/benevolent-games/argv#readme
源码仓库：https://github.com/benevolent-games/argv

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

- 包体积（解压后）：235 kB，184 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-01-06T01:48:39.277Z
- 最新版本发布：2026-02-21T05:38:59.937Z
- 近 30 天下载量：2744（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 2 个）

## 中文简介

命令行参数解析器

## 安装

```sh
npm install @benev/argv
```

也可以使用：`pnpm add @benev/argv`、`yarn add @benev/argv`、`bun add @benev/argv`

## README

# 🎛️ `@benev/argv`

**对打字符的最大命令行解析器, 也许**

用于制作节点 cli 程序  
难以置信的打字类型推论  
零依赖关系  
自由公开的源头,只为你

  

## 自动生成 `--help` 页次

```sh
pizza --help
```

![](https://imgur.com/aSAP8cb.png)

```sh
pizza large --pepperoni --slices 3

# or, any way you like it
pizza --slices=9 large
pizza medium -p --slices=5
pizza small --pepperoni="no" --slices="2"
```

  

## 盖起你的 `cli`

1.  安装 `@benev/argv` 通过 npm
    
    ```sh
    npm i @benev/argv
    ```
    
2.  导入东西
    
    ```ts
    import {cli, command, arg, param, string, number} from "@benev/argv"
    ```
    
3.  指定您的 cli, 并进行解析
    
    ```ts
    const {args, params} = cli(process.argv, {
      name: "pizza",
      commands: command({
        args: [
          arg("size").required(string),
        ],
        params: {
          slices: param.default(number, "1"),
          pepperoni: param.flag("p"),
        },
      }),
    }).tree
    ```
    
4.  现在,你有你的标语和标语
    
    ```js
    args.size // "large"
    params.slices // 5
    params.pepperoni // true
    ```
    
    -   这是接收您的参数和参数的"平面策略".  
        简单,简单!
5.  _**你们这种人都是自发的!**_  
    我花了很长的时间才让它这么优雅和酷.

  

## 配置你的cli的 `args` 财务报告和审定财务报表 `params`

-   我们先发出命令
    
    ```ts
    command({
      args: [],
      params: {},
    })
    ```
    
-   命令可以选择接受 `help` 字符串
    
    ```ts
    command({
      help: "what a time to be alive!",
      args: [],
      params: {},
    })
    ```
    
-   让我们添加位置参数
    
    ```ts
    command({
      args: [
        arg("active").required(boolean),
        arg("count").default(number, "101"),
        arg("name").optional(string),
      ],
      params: {},
    })
    ```
    
    -   参数在一个阵列中,所以每个阵列都需要一个名称,例如上面的"活性"
    -   有三个模式, `required`, (中文(简体) ), `default`,以及 `optional`
    -   `default` 需要一个倒数
    -   有三个基本类型, `string`, (中文(简体) ), `number`,以及 `boolean`,但你可以 自己类型
-   现在,让我们谈谈抛物
    
    ```ts
    command({
      args: [],
      params: {
        active: param.required(boolean),
        count: param.default(number, "101"),
        name: param.optional(string),
        verbose: param.flag("-v"),
      },
    })
    ```
    
    -   相当相似,但看到名字不同了吗?
    -   有种叫新车厢的 `flag`当然,这是自动的 `boolean` (怎么会是其他的?)

### 参数和参数的验证

-   你可以设置一个 `validate` 函数在任意 `arg` 或者说 `param`
    
    ```ts
    arg("quality").optional(number, {
      validate: n => {
        if (n > 100) throw new Error("to big")
        if (n < 0) throw new Error("to smol")
        return n
      },
    })
    ```
    
    -   如果您在其中投出任何错误 `validate`,它将被打印出来 所有良好的用户

### `help` 到处都是!

-   事实上,每个 `arg` 财务报告和审定财务报表 `param` 可以拥有自己的 `help`
    
    ```ts
    command({
      help: "it's the best command, nobody makes commands like me",
    
      args: [
        arg("active").required(boolean, {
          help: "all systems go?",
        }),
    
        arg("count").default(number, "101", {
          help: "number of dalmatians",
        }),
    
        arg("name").optional(string, {
          help: `
            see this multi-line string?
            it will be trimmed all nicely on the help page.
          `
        }),
      ],
    
      params: {
        active: param.required(boolean, {
          help: "toggle this carefully!",
        }),
    
        count: param.default(number, "101", {
          help: "classroom i'm late for",
        }),
    
        name: param.optional(string, {
          help: "pick your pseudonym",
        }),
    
        verbose: param.flag("-v", {
          help: "going loud",
        }),
      },
    })
    ```
    

### `list` 帮助者

-   好吧,这是严重的疯狂酷, 看这个
    
    ```ts
    param.required(list(string))
    ```
    
-   您可以在 `list` 帮助者
    -   用户输入逗号分隔值 `mp3,wav,ogg`
    -   获得数组 `["mp3", "wav", "ogg"]`
-   与 _任何类型_,像数字和这样的
    
    ```ts
    param.required(list(number))
    ```
    
    -   现在你得到一个 `number[]` 数组( 不是字符串)
    -   对, `list` 保存类型验证

### `choice` 帮助者

-   用户可以选择允许的值之一
    
    ```ts
    param.required(string, choice(["thick", "thin"]))
    ```
    
-   你也可以加入帮助它
    
    ```ts
    param.required(string, choice(["thick", "thin"], {
      help: "made with organic whole-wheat flour",
    }))
    ```
    

### `multipleChoice` 帮助者

-   允许用户选择多个允许的选择
    
    ```ts
    param.required(string, multipleChoice(["bacon", "lettuce", "tomatoes"]))
    ```
    
-   您可以添加帮助,并决定是否允许用户作出零选择
    
    ```ts
    param.required(string, choice(["bacon", "lettuce", "tomatoes"], {
      help: "all available ingredients are gmo'd",
      zeroAllowed: true, // defaults to false
    }))
    ```
    

  

## ++多树 `commands`

-   页:1 `commands` 对象是一个递归树 `command` 叶子
    
    ```ts
    const {tree} = cli(process.argv, {
      name: "converter",
      commands: {
        image: command({
          args: [],
          params: {
            quality: param.required(number),
          },
        }),
        media: {
          audio: command({
            args: [],
            params: {
              mono: param.required(boolean),
            },
          }),
          video: command({
            args: [],
            params: {
              codec: param.required(string),
            },
          })
        },
      },
    })
    ```
    

### 树战略

-   你明白吗 `tree` 反映其形状的天体
    
    ```ts
    tree.image?.params.quality // 9
    tree.media.audio?.mono // false
    tree.media.video?.codec // "av1"
    ```
    
    -   所有的命令都是 `undefined` 除了"选定"命令
    -   对,所有的打字都行

### 命令执行策略

-   您可以选择提供每个命令的自动同步 `execute` 函数
    
    ```ts
    command({
      args: [],
      params: {
        active: param.required(boolean),
        count: param.default(number, "101"),
      },
      async execute({params}) {
        params.active // true
        params.count // 101
      },
    })
    ```
    
    -   您的执行函数收到相关的全类型 `args`, (中文(简体) ), `params`和一些东西
-    `execute` 函数可以通过扔出一个 `ExecutionError`
    
    ```ts
    import {ExecutionError, command} from "@benev/argv"
    
    async execute({params}) {
      throw new ExecutionError("scary error printed in red!")
    }
    ```
    
-   如果你选择使用这个命令执行策略, 那你需要调用您的 cli 的终局 `execute` 函数
    
    ```ts
    // 👇 awaiting cli execution
    await cli(process.argv, {
      name: "pizza",
      commands: {
        meatlovers: command({
          args: [],
          params: {
            meatiness: param.required(number),
          },
          async execute({params}) {
            console.log(params.meatiness) // 9
          },
        }),
        hawaiian: command({
          args: [],
          params: {
            pineappleyness: param.required(number),
          },
          async execute({params}) {
            console.log(params.pineappleyness) // 8
          },
        }),
      },
    }).execute()
      // ☝️ calling cli final execute
    ```
    

  

## qq 自定义类型

-   真不敢相信,我得到了所有的类型 工作所有与定制类型
-   做自己的类型很容易
    
    ```ts
    const date = asType({
      name: "date",
      coerce: string => new Date(string),
    })
    ```
    
    -   页:1 `name` 在帮助页面中显示
    -   页:1 `coerce` 函数需要字符串输入,然后将其变成任何您喜欢的
-   那样你就可以像正常人一样用它们来配乐
    
    ```ts
    param.required(date)
    ```
    
-   嘿,为什么我们不列出他们的名单呢
    
    ```ts
    param.required(list(date))
    ```
    
-   感觉很不舒服吗? 用这个奇怪的提示来制作一组自定义类型
    
    ```ts
    const myTypes = asTypes({
      date: string => new Date(string),
      integer: string => Math.floor(Number(string)),
    })
    ```
    
    -   `asTypes` 将使用对象的属性名称作为类型 `name`
-   您的自定义类型可以丢出出错误, 并起到校验作用
    
    ```ts
    const integer = asType({
      name: "integer",
      coerce: string => {
        const n = Number(string)
    
        if (isNaN(n))
          throw new Error("not a number")
    
        if (!Number.isSafeInteger(n))
          throw new Error("not a safe integer")
    
        return n
      },
    })
    ```
    

  

## qq 自定义主题

-   您可以为您的 -- help 页设置主题
    
    ```ts
    import {themes} from "@benev/argv"
    
    await cli(process.argv, {
    
      // the default theme
      theme: themes.standard,
    
      ...otherStuff,
    }).execute()
    ```
    
    -   也许试试 `themes.seaside` 更冷静的氛围
    -   如果你讨厌乐趣,用 `themes.noColor` 以禁用 ansi 颜色
-   做你自己的主题像这样
    
    ```ts
    import {theme, color} from "@benev/argv"
    
    const seaside = theme({
      plain: [color.white],
      error: [color.brightRed, color.bold],
      program: [color.brightCyan, color.bold],
      command: [color.cyan, color.bold],
      property: [color.blue],
      link: [color.brightBlue, color.underline],
      arg: [color.brightBlue, color.bold],
      param: [color.brightBlue, color.bold],
      flag: [color.brightBlue],
      required: [color.cyan],
      mode: [color.blue],
      type: [color.brightBlue],
      value: [color.cyan],
    })
    ```
    

  

## 给我一颗 gi星!

-   我太费劲了
-   请针对任何问题或问题提出问题
-   也许做一个很酷的帮助主题 并提交一个PR

## 常见问题

### @benev/argv 是什么？

命令行参数解析器

### 如何安装 @benev/argv？

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

### @benev/argv 支持 TypeScript 吗？

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

### @benev/argv 支持 ESM 还是 CommonJS？

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

### @benev/argv 可以商用吗？

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

### @benev/argv 的下载量有多少？

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

### @benev/argv 还在维护吗？

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