# arg 中文文档

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

版本：5\.0\.2
npm 元数据更新时间：2026-02-25T04:30:21.078Z
中文译文更新时间：2026-11-05T15:00:24.952Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：13.7 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2012-06-01T15:39:02.676Z
- 最新版本发布：2022-06-05T18:20:09.200Z
- 近 30 天下载量：410024258（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 0 个）

## 中文简介

解析器

## 安装

```sh
npm install arg
```

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

## README

# 参数

`arg` 是一个无偏移的 CLI 参数解析器.

## 安装

```bash
npm install arg
```

## 使用量

`arg()` 需要1或2个参数:

1.  命令行规格对象(见下文)
2.  解析选项( E)_可选_,默认为 `{permissive: false, argv: process.argv.slice(2), stopAtPositional: false}`(中文(简体) )

它返回一个带有命令行上任何值的对象( 丢失选项因此是) ),从由此产生的对象中消失。 arg 不进行验证/要求检查 - 我们 由申请决定.

所有未被选项所消耗的参数(通称"外"参数) 添加到 `result._`,这是 _永远_ 数组(即使没有通过额外参数, 返回空数组.

```javascript
const arg = require('arg');

// `options` is an optional parameter
const args = arg(
    spec,
    (options = { permissive: false, argv: process.argv.slice(2) })
);
```

例如:

```console
$ node ./hello.js --verbose -vvv --port=1234 -n 'My name' foo bar --tag qux --tag=qix -- --foobar
```

```javascript
// hello.js
const arg = require('arg');

const args = arg({
    // Types
    '--help': Boolean,
    '--version': Boolean,
    '--verbose': arg.COUNT, // Counts the number of times --verbose is passed
    '--port': Number, // --port <number> or --port=<number>
    '--name': String, // --name <string> or --name=<string>
    '--tag': [String], // --tag <string> or --tag=<string>

    // Aliases
    '-v': '--verbose',
    '-n': '--name', // -n <string>; result is stored in --name
    '--label': '--name' // --label <string> or --label=<string>;
    //     result is stored in --name
});

console.log(args);
/*
{
    _: ["foo", "bar", "--foobar"],
    '--port': 1234,
    '--verbose': 4,
    '--name': "My name",
    '--tag': ["qux", "qix"]
}
*/
```

每个键的QQ值对的值要么是一个类型(函数或\[函数\]),要么是一个字符串(表示别名).

-   如果是函数,则将参数值的字符串值传递给它, 和返回值作为最终值.
    
-   对于数组,唯一的元素 _必须_ 是一个类型函数。 矩阵类型表示 以及由此产生的返回中的价值 对象是一个数组,其中包含所有使用指定旗帜传递的值.
    
-   以弦为例,则起别名. 如果一面旗子被通过 匹配 _键_, (中文(简体) ), 接下来 _价值_ 替换为它的位置.
    

类型函数通过三个参数:

1.  参数值( 总是字符串)
2.  参数名称( 如 . `--label`(中文(简体) )
3.  目的地的上一个值(可用于类似减少操作或支持 `-v` 多次次数等)

这意味着内置 `String`, (中文(简体) ), `Number`,以及 `Boolean` 类型构造器“只是工作”作为类型函数.

请注意: `Boolean` 财务报告和审定财务报表 `[Boolean]` 有特殊待遇 - 一个选项论据是 _没有_ 消费或通过,但相反 `true` 实值 已经返回。 这些选项被称为"旗".

对于希望表现为旗帜的自定义处理器,您可以将功能传递到 `arg.flag()`数字 :

```javascript
const arg = require('arg');

const argv = [
    '--foo',
    'bar',
    '-ff',
    'baz',
    '--foo',
    '--foo',
    'qux',
    '-fff',
    'qix'
];

function myHandler(value, argName, previousValue) {
    /* `value` is always `true` */
    return 'na ' + (previousValue || 'batman!');
}

const args = arg(
    {
        '--foo': arg.flag(myHandler),
        '-f': '--foo'
    },
    {
        argv
    }
);

console.log(args);
/*
{
    _: ['bar', 'baz', 'qux', 'qix'],
    '--foo': 'na na na na na na na na batman!'
}
*/
```

还有, `arg` 提供名为“ 帮助” 的参数处理器 `arg.COUNT`,相当于 `[Boolean]` 参数的 `.length` 属性 - 在命令行上传递以密钥表示的布尔旗次数. 例如,这是你如何执行 `ssh`动词的多级( :`-vvvv` 成为最动词.

```javascript
const arg = require('arg');

const argv = ['-AAAA', '-BBBB'];

const args = arg(
    {
        '-A': arg.COUNT,
        '-B': [Boolean]
    },
    {
        argv
    }
);

console.log(args);
/*
{
    _: [],
    '-A': 4,
    '-B': [true, true, true, true]
}
*/
```

### 选项

如果指定了第二个参数并且是一个对象,它会指定解析选项来修改 `arg()`。 。 。 .

#### `argv`

如果您已经切片或生成了一些要解析的原始参数( 而不是让 ) `arg` 切下来 `process.argv`您可以在 `argv` 选项.

例如:

```javascript
const args = arg(
    {
        '--foo': String
    },
    {
        argv: ['hello', '--foo', 'world']
    }
);
```

结果是:

```javascript
const args = {
    _: ['hello'],
    '--foo': 'world'
};
```

#### `permissive`

何时 `permissive` 设置为 `true`, (中文(简体) ), `arg` 将推动任何未知参数 到“ extra” 参数数组(`result._`)而不是抛出一个关于 不明旗帜.

例如:

```javascript
const arg = require('arg');

const argv = [
    '--foo',
    'hello',
    '--qux',
    'qix',
    '--bar',
    '12345',
    'hello again'
];

const args = arg(
    {
        '--foo': String,
        '--bar': Number
    },
    {
        argv,
        permissive: true
    }
);
```

结果是:

```javascript
const args = {
    _: ['--qux', 'qix', 'hello again'],
    '--foo': 'hello',
    '--bar': 12345
};
```

#### `stopAtPositional`

何时 `stopAtPositional` 设置为 `true`, (中文(简体) ), `arg` 将停止第一次解析 位置参数.

例如:

```javascript
const arg = require('arg');

const argv = ['--foo', 'hello', '--bar'];

const args = arg(
    {
        '--foo': Boolean,
        '--bar': Boolean
    },
    {
        argv,
        stopAtPositional: true
    }
);
```

结果是:

```javascript
const args = {
    _: ['hello', '--bar'],
    '--foo': true
};
```

### 错误

有些错误 `arg` 投掷提供 `.code` 属性,以帮助从用户错误中恢复,或 区分用户出错和开发者出错(bug).

##### (阿根廷语)

如果一个未知的选项( 未在 spec 对象中定义) 被通过, 则出现代码错误 `ARG_UNKNOWN_OPTION` 将扔出 :

```js
// cli.js
try {
    require('arg')({ '--hi': String });
} catch (err) {
    if (err.code === 'ARG_UNKNOWN_OPTION') {
        console.log(err.message);
    } else {
        throw err;
    }
}
```

```shell
node cli.js --extraneous true
Unknown or unexpected option: --extraneous
```

# 财务问题

前所问之数相问答

### 我该怎么和他争吵 `arg`? 吗?

自己做断言,例如:

```javascript
const args = arg({ '--name': String });

if (!args['--name']) throw new Error('missing required argument: --name');
```

# 许可证

释放 [MIT 许可证](https://npmcn.com/package/arg/LICENSE.md)。 。 。 .

## 常见问题

### arg 是什么？

解析器

### 如何安装 arg？

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

### arg 支持 TypeScript 吗？

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

### arg 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### arg 可以商用吗？

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

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

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

### arg 还在维护吗？

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