# @pkgjs/parseargs 中文文档

规范地址：https://npmcn.com/package/%40pkgjs/parseargs/

版本：0\.11\.0
npm 元数据更新时间：2023-07-12T19:06:07.630Z
中文译文更新时间：2026-11-05T15:34:31.779Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：74.2 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=14
- 运行依赖：0 个
- 首次发布：2022-01-22T19:26:33.809Z
- 最新版本发布：2022-10-10T14:18:44.810Z
- 近 30 天下载量：367059674（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 0 个）

## 中文简介

将今后关于 `util.parseArgs()`

## 安装

```sh
npm install @pkgjs/parseargs
```

也可以使用：`pnpm add @pkgjs/parseargs`、`yarn add @pkgjs/parseargs`、`bun add @pkgjs/parseargs`

## README

# 参数

[![Coverage](https://img.shields.io/nycrc/pkgjs/parseargs)](https://github.com/pkgjs/parseargs/blob/main/.nycrc)

多元填充量 `util.parseArgs()`

## `util.parseArgs([config])`

> 稳定性: 1 - 实验

-   `config` {Object} 曾经为解析和配置提供参数 解说者. `config` 支持以下属性 :
    
    -   `args` {字符串} 参数字符串的数组 . **默认 :** `process.argv` 与 `execPath` 财务报告和审定财务报表 `filename` 已删除.
    -   `options` {Object} 用来描述解析器已知的参数 . 键 `options` 选项的长名和值是一个 {对象} 接受以下属性 :
        -   `type` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你来干什么? 论证类型,必须是 `boolean` 或者说 `string`。 。 。 .
        -   `multiple` \[布尔\] 是否可以提供多选项 时间。 若为 `true`,所有值将在数组中收集。 若为 `false`,该选项的值为最后赢. **默认 :** `false`。 。 。 .
        -   `short` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你来干什么? 选项的单个字符别名 .
        -   `default` {弦 \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* 默认选项 当它不是由参数设置时值。 它必须是同一种类型 页:1 `type` 属性。 何时 `multiple` 实值 `true`,它必须是数组.
    -   `strict` \[布尔\] 未知参数时是否出现错误 被遇到,或者被传递的参数与 `type` 配置于 `options`。 。 。 . **默认 :** `true`。 。 。 .
    -   `allowPositionals` \[布尔\] 此命令是否接受位置 参数. **默认 :** `false` 若为 `strict` 实值 `true`,否则 `true`。 。 。 .
    -   `tokens` \[布尔\] 复还解相相. 用于扩展 从新增检查到后处理 各种迹象. **默认 :** `false`。 。 。 .
-   返回 : {对象} 解析的命令行参数 :
    
    -   `values` {对象} 以 { string} 绘制解析选项名称的映射 或 {布尔} 值.
    -   `positionals` {字符串} \[ 立场论证.
    -   `tokens` {Object\[\] }\\ 未定义} 见 [解析符号](https://npmcn.com/package/%40pkgjs/parseargs/#readme-parseargs-tokens) 节。 只有在 `config` 包含 `tokens: true`。 。 。 .

为命令行参数解析提供更高层次的 API 与 `process.argv` 直接说 对预期的参数进行说明 并返回带有解析选项和位置的结构化对象.

```mjs
import { parseArgs } from 'node:util';
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f'
  },
  bar: {
    type: 'string'
  }
};
const {
  values,
  positionals
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []
```

```cjs
const { parseArgs } = require('node:util');
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f'
  },
  bar: {
    type: 'string'
  }
};
const {
  values,
  positionals
} = parseArgs({ args, options });
console.log(values, positionals);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []
```

`util.parseArgs` 是实验性的 行为可能改变 请加入 对话 [pkgjs/公园](https://github.com/pkgjs/parseargs) 对设计作出贡献.

### `parseArgs` `tokens`

详细分析信息可用以添加习惯行为 指定 `tokens: true` 在配置中. 返回的符号有属性描述:

-   所有符号
    -   `kind` {字符串} “ 选项” 、 “ 位置” 或 “ 选项终止器 ” 之一 .
    -   `index` {编号} 元素索引 `args` 包含符号。 所以说 符号的源参数是 `args[token.index]`。 。 。 .
-   选项符号
    -   `name` {字符串}选项的长名 .
    -   `rawName` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你来干什么? 参数中如何使用选项 `-f` 联 合 国 `--foo`。 。 。 .
    -   `value` {字符串{未定义} 参数中指定的选项值 . 未定义布尔选项 .
    -   `inlineValue` {boolean }\\ 未定义} 是否指定内置选项值, 喜欢 `--foo=bar`。 。 。 .
-   位置符号
    -   `value` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你来干什么? 参数中的位置参数值(即:. `args[index]`) (中文(简体) ).
-   选项终止符

返回的令牌的顺序与输入参数中遇到的顺序相符合. 选项 超过一次在方格中出现,为每种用途产生一个符号。 短选项 类群体 `-xy` 扩展为每个选项的符号 。 这么说吧 `-xxx` 生产 三相相证相.

例如,使用返回的符号添加对否定选项的支持 喜欢 `--no-color`,可重新处理以更改存储的值 对于否定的选项.

```mjs
import { parseArgs } from 'node:util';

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });
```

```cjs
const { parseArgs } = require('node:util');

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// Reprocess the option tokens and overwrite the returned values.
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // Store foo:false for --no-foo
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // Resave value so last one wins if both --foo and --no-foo.
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });
```

显示否定选项的示例用法, 当使用选项时 以多种方式,最后一种方式获胜.

```console
$ node negate.js
{ logfile: 'default.log', color: undefined }
$ node negate.js --no-logfile --no-color
{ logfile: false, color: false }
$ node negate.js --logfile=test.log --color
{ logfile: 'test.log', color: true }
$ node negate.js --no-logfile --logfile=test.log --color --no-color
{ logfile: 'test.log', color: false }
```

* * *

## 目录

-   [`util.parseArgs([config])`](https://npmcn.com/package/%40pkgjs/parseargs/#readme-utilparseargsconfig)
-   [范围](https://npmcn.com/package/%40pkgjs/parseargs/#readme-scope)
-   [版本匹配](https://npmcn.com/package/%40pkgjs/parseargs/#readme-version-matchups)
-   [开始](https://npmcn.com/package/%40pkgjs/parseargs/#readme--getting-started)
-   [捐款](https://npmcn.com/package/%40pkgjs/parseargs/#readme--contributing)
-   [💡 `process.mainArgs` 提议](https://npmcn.com/package/%40pkgjs/parseargs/#readme--processmainargs-proposal)
    -   [执行:](https://npmcn.com/package/%40pkgjs/parseargs/#readme-implementation)
-   [实例](https://npmcn.com/package/%40pkgjs/parseargs/#readme--examples)
-   [F.A.Qs (中文(简体) )](https://npmcn.com/package/%40pkgjs/parseargs/#readme-faqs)
-   [链接和资源( R)](https://npmcn.com/package/%40pkgjs/parseargs/#readme-links--resources)

* * *

## 范围

在节点.js提供的内容上,已经可以构建出巨大的参数解析模块;刺入的API被这些模块所抽象出. 因此,process.parseArgs()并不一定是针对图书馆作者的;它旨在开发简单的CLI工具,临时hoc脚本,已部署的Node.js应用程序,以及学习材料.

极难提供一个既能对这些节点用户友好又能够扩展供图书馆利用的API。 我们选择优先处理这些使用案例,因为这些案例目前没有得到Node.js的API的服务.

* * *

## 版本匹配

| 节点.js | @pkgjs/ parseArgs (英语) |
| --- | --- |
| [v18.3.0 (韩语)](https://nodejs.org/docs/latest-v18.x/api/util.html#utilparseargsconfig) | [页:1](https://github.com/pkgjs/parseargs/tree/v0.9.1#utilparseargsconfig) |
| [页:1](https://nodejs.org/dist/latest-v16.x/docs/api/util.html#utilparseargsconfig), (中文(简体) ), [页:1](https://nodejs.org/docs/latest-v18.x/api/util.html#utilparseargsconfig) | [0.10.0 (中文(简体) )](https://github.com/pkgjs/parseargs/tree/v0.10.0#utilparseargsconfig) |

* * *

## 开始

1.  **安装依赖关系 .**
    
    ```bash
    npm install
    ```
    
2.  **打开索引.js文件开始编辑!**
    
3.  **通过测试文件调用 parseArgs 来测试您的代码**
    
    ```bash
    npm test
    ```
    

* * *

## 捐款

任何想为倡议出力的人,都欢迎! 请先读一下 [贡献指南](https://npmcn.com/package/%40pkgjs/parseargs/CONTRIBUTING.md)

此外,阅读 [`Examples w/ Output`](https://npmcn.com/package/%40pkgjs/parseargs/#readme--examples-w-output) 该文件的章节将是一个最佳的方法,使自己熟悉ParseArgs () 的目标预期行为.

此软件包是使用 [磁带](https://www.npmjs.com/package/tape) 作为它的测试工具.

* * *

## 💡 `process.mainArgs` 提议

> 说明: 这可以独立于 `util.parseArgs()` 建议/工作.

### 执行:

```javascript
process.mainArgs = process.argv.slice(process._exec ? 1 : 2)
```

* * *

## 实例

```js
const { parseArgs } = require('@pkgjs/parseargs');
```

```js
const { parseArgs } = require('@pkgjs/parseargs');
// specify the options that may be used
const options = {
  foo: { type: 'string'},
  bar: { type: 'boolean' },
};
const args = ['--foo=a', '--bar'];
const { values, positionals } = parseArgs({ args, options });
// values = { foo: 'a', bar: true }
// positionals = []
```

```js
const { parseArgs } = require('@pkgjs/parseargs');
// type:string & multiple
const options = {
  foo: {
    type: 'string',
    multiple: true,
  },
};
const args = ['--foo=a', '--foo', 'b'];
const { values, positionals } = parseArgs({ args, options });
// values = { foo: [ 'a', 'b' ] }
// positionals = []
```

```js
const { parseArgs } = require('@pkgjs/parseargs');
// shorts
const options = {
  foo: {
    short: 'f',
    type: 'boolean'
  },
};
const args = ['-f', 'b'];
const { values, positionals } = parseArgs({ args, options, allowPositionals: true });
// values = { foo: true }
// positionals = ['b']
```

```js
const { parseArgs } = require('@pkgjs/parseargs');
// unconfigured
const options = {};
const args = ['-f', '--foo=a', '--bar', 'b'];
const { values, positionals } = parseArgs({ strict: false, args, options, allowPositionals: true });
// values = { f: true, foo: 'a', bar: true }
// positionals = ['b']
```

* * *

## F.A.Qs (中文(简体) )

-   这是 `cmd --foo=bar baz` 与 `cmd baz --foo=bar`? 吗?
    -   对
-   解析器执行函数吗 ?
    -   没有
-   解析器是否根据输入执行多个函数中的一个?
    -   没有
-   子命令能否采取不同于主命令的选项?
    -   没有
-   如果没有选项匹配, 输出是否生成帮助 ?
    -   没有
-   它是否产生了短暂的使用? 喜欢: `usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]`
    -   否( 没有使用/ 帮助)
-   用户是否提供长使用文本 ? 每个选择? 整个指挥部?
    -   没有
-   子命令( 如果已执行) 是否有自己的使用输出 ?
    -   没有
-   如果用户运行, 是否使用打印 `cmd --help`? 吗?
    -   没有
-   是否设定 `process.exitCode`? 吗?
    -   没有
-   打印到 Stderr 还是 stdout ?
    -   不详
-   它检查类型吗? (说,指定一个选项是一个布尔,数字等)
    -   没有
-   一个选项能有多个类型吗? (弦或虚等
    -   没有
-   用户能定义一个类型吗 ? (说, `type: path` 调用 `path.resolve()` (关于争论。 )
    -   没有
-   一个 `--foo=0o22` 0,22,18,还是"0o22"?
    -   `"0o22"`
-   它强迫类型?
    -   没有
-   对 `--no-foo` 强迫和强迫 `--foo=false`为了所有的选择 只有布尔选项吗?
    -   不,它设置 `{values:{'no-foo': true}}`
-   这是 `--foo` 与 `--foo=true`只有已知的布尔人? 只在最后吗?
    -   不,他们不一样。 没有特别处理 `true` 作为一个值,所以它只是另一个字符串.
-   它读取环境变量吗? 爱,是 `FOO=1 cmd` 与 `cmd --foo=1`? 吗?
    -   没有
-   未知参数是否引起错误 ? 他们解剖了吗? 他们是否被视为立场争论?
    -   不,他们是被解析的, 不作为位置
-   对 `--` 表示选项的结束吗 ?
    -   对
-   这是 `--` 作为立场列入?
    -   没有
-   这是 `program -- foo` 与 `program foo`? 吗?
    -   是的,两家店 `{positionals:['foo']}`
-   API是否具体说明是否 `--` 是否在场/相关?
    -   没有
-   这是 `-bar` 与 `--bar`? 吗?
    -   没有, `-bar` 是一个简短的选项或选项,其扩展逻辑遵循 [POSIX.1-2017年实用语法准则](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html)。 。 。 . `-bar` 扩展至 `-b`, (中文(简体) ), `-a`, (中文(简体) ), `-r`。 。 。 .
-   这是 `---foo` 与 `--foo`? 吗?
    -   没有
    -   第一个是长选项命名 `'-foo'`
    -   第二个选项是一个很长的选项 `'foo'`
-   这是 `-` 立场? ie, `bash some-test.sh | tap -`
    -   对

## 链接和资源( R)

-   [初始工具问题](https://github.com/nodejs/tooling/issues/19)
-   [初步提案](https://github.com/nodejs/node/pull/35015)
-   [参数建议](https://github.com/nodejs/node/pull/42675)

## 常见问题

### @pkgjs/parseargs 是什么？

将今后关于 util\.parseArgs\(\)

### 如何安装 @pkgjs/parseargs？

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

### @pkgjs/parseargs 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/pkgjs\_\_parseargs 是否存在。

### @pkgjs/parseargs 支持 ESM 还是 CommonJS？

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

### @pkgjs/parseargs 需要什么版本的 Node\.js？

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

### @pkgjs/parseargs 可以商用吗？

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

### @pkgjs/parseargs 的下载量有多少？

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

### @pkgjs/parseargs 还在维护吗？

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