yargs-parser

中文文档

22.0.0发布于 2025/05/27ISCES Module零依赖近 30 天下载 11.1亿

yargs使用的强大选项解析器

文档目录28 节

例子
Deno例子
ESM的例子
API
解析器(args,选择= {})
要求(yargs-parser)管理部(args,选择= {})
配置
空头期权组
“骆峰式”扩张
通过点
解析数据
解析位置数字
布尔否定
结合数组
重复参数数组
平放重复数组
贪婪的数组
Nargs吃期权
否定前缀
填充,
设置占位符键
停止无选择
带别名
条虚线
未知选项作为参数
支持的Node.js版本
特别感谢
许可证

yargs-parser

nycrc config on GitHub

的强大选项解析器 yargs。

参观 yargs网站有关更多示例，以及详细的使用说明。

例子

npm i yargs-parser --save

const argv = require('yargs-parser')(process.argv.slice(2))
console.log(argv)

$ node example.js --foo=33 --bar hello
{ _: [], foo: 33, bar: 'hello' }

或者解析字符串！

const argv = require('yargs-parser')('--foo=99 --bar=33')
console.log(argv)

{ _: [], foo: 99, bar: 33 }

类型之前转换混合类型的数组 yargs-parser：

const parse = require('yargs-parser')
parse(['-f', 11, '--zoom', 55].join(' '))   // <-- array to string
parse(['-f', 11, '--zoom', 55].map(String)) // <-- array of strings

Deno例子

的 v19 yargs-parser 支持 Deno：

import parser from "https://deno.land/x/yargs_parser/deno.ts";

const argv = parser('--foo=99 --bar=9987930', {
  string: ['bar']
})
console.log(argv)

ESM的例子

的 v19 yargs-parser 支持ESM (在Node.js和浏览器中）：

node . js:

import parser from 'yargs-parser'

const argv = parser('--foo=99 --bar=9987930', {
  string: ['bar']
})
console.log(argv)

浏览器:

<!doctype html>
<body>
  <script type="module">
    import parser from "https://unpkg.com/[email protected]/browser.js";

    const argv = parser('--foo=99 --bar=9987930', {
      string: ['bar']
    })
    console.log(argv)
  </script>
</body>

API

解析器(args,选择= {})

解析命令行参数，返回键和值的简单映射。

预计:

args：一个字符串或字符串数组，表示要解析的选项。
opts：提供一组提示说明如何 args 应该被解析：
- opts.alias：一个对象，表示一个键的一组别名： {alias: {foo: ['f']}}。
- opts.array：表示将键解析为数组： {array: ['foo', 'bar']}。
  指示键应该作为数组解析，并强制为布尔值/数字：
  {array: [{ key: 'foo', boolean: true }, {key: 'bar', number: true}]}。
- opts.boolean参数应解析为布尔值： {boolean: ['x', 'y']}。
- opts.coerce：提供自定义同步函数，从所提供的参数返回强制值（或抛出错误）。对于数组，整个数组只调用该函数一次：
  {coerce: {foo: function (arg) {return modifiedArg}}}。
- opts.config：表示配置文件的路径（该文件将被加载和解析）。
- opts.configObjects要解析的：configuration对象，它们的属性将被设置为参数：
  {configObjects: [{'x': 5, 'y': 33}, {'z': 44}]}。
- opts.configuration为yargs解析器提供配置选项(参见：配置）.
- opts.count：指示应用作计数器的键，例如： -vvv ＝ {v: 3}。
- opts.default：提供键的默认值： {default: {x: 33, y: 'hello world!'}}。
- opts.envPrefix：环境变量(process.env使用所提供的前缀进行解析。
- opts.narg：指定密钥的要求 n 参数: {narg: {x: 2}}。
- opts.normalize： path.normalize() 将应用于设置为此键的值。
- opts.number键应被视为数字。
- opts.string键应该被视为字符串（即使它们类似于数字） -x 33）.

返回:

obj：表示的解析值的对象 args
- key/value：每个参数及其别名的键值对。
- _：表示位置参数的数组。
- (可选) --：一个在结束选项标志后带有参数的数组 --。

要求(yargs-parser)管理部(args,选择= {})

方法所需的详细信息 yargs引擎。

预计:

args：一个字符串或字符串数组，表示要解析的选项。
opts：提供一组提示说明如何 args，输入等于 require('yargs-parser')(args, opts={})。

返回:

argv：表示的解析值的对象 args
- key/value：每个参数及其别名的键值对。
- _：表示位置参数的数组。
- (可选) --：一个在结束选项标志后带有参数的数组 --。
error：如果在解析过程中发生异常，则填充错误对象。
aliases：通过组合中的列表构建的别名推断列表 opts.alias。
newAliases通过骆驼扩展添加的新别名
- boolean： { fooBar: true }
defaulted创建的任何新参数 opts.default，不包含别名。
- boolean： { foo: true }
configuration：由默认设置和给出 opts.configuration。

配置

yargs解析器对提供的键应用几个自动转换在 args．控件可以打开和关闭这些功能 configuration 场的 opts。

var parsed = parser(['--no-dice'], {
  configuration: {
    'boolean-negation': false
  }
})

空头期权组

默认值: true。
关键: short-option-groups。

一组短选项应该被视为布尔标志吗？

$ node example.js -abc
{ _: [], a: true, b: true, c: true }

如果禁用:

$ node example.js -abc
{ _: [], abc: true }

“骆峰式”扩张

默认值: true。
关键: camel-case-expansion。

用连字符连接的参数是否应该扩展为驼峰式别名？

$ node example.js --foo-bar
{ _: [], 'foo-bar': true, fooBar: true }

如果禁用:

$ node example.js --foo-bar
{ _: [], 'foo-bar': true }

通过点

默认值: true
关键: dot-notation

应该键包含 . 被当作物品对待？

$ node example.js --foo.bar
{ _: [], foo: { bar: true } }

如果禁用:

$ node example.js --foo.bar
{ _: [], "foo.bar": true }

解析数据

默认值: true
关键: parse-numbers

看起来像数字的键应该被这样对待吗？

$ node example.js --foo=99.3
{ _: [], foo: 99.3 }

如果禁用:

$ node example.js --foo=99.3
{ _: [], foo: "99.3" }

解析位置数字

默认值: true
关键: parse-positional-numbers

看起来像数字的位置键是否应该被这样对待？

$ node example.js 99.3
{ _: [99.3] }

如果禁用:

$ node example.js 99.3
{ _: ['99.3'] }

布尔否定

默认值: true
关键: boolean-negation

变量的前缀应该是 --no 被视为否定？

$ node example.js --no-foo
{ _: [], foo: false }

如果禁用:

$ node example.js --no-foo
{ _: [], "no-foo": true }

结合数组

默认值: false
关键: combine-arrays

当由命令行参数和配置文件。

重复参数数组

默认值: true
关键: duplicate-arguments-array

当参数重复时，是否应该将其强制转换为数组：

$ node example.js -x 1 -x 2
{ _: [], x: [1, 2] }

如果禁用:

$ node example.js -x 1 -x 2
{ _: [], x: 2 }

平放重复数组

默认值: true
关键: flatten-duplicate-arrays

当数组参数重复时，应该强制转换为单个数组吗？

$ node example.js -x 1 2 -x 3 4
{ _: [], x: [1, 2, 3, 4] }

如果禁用:

$ node example.js -x 1 2 -x 3 4
{ _: [], x: [[1, 2], [3, 4]] }

贪婪的数组

默认值: true
关键: greedy-arrays

数组应该在其标志后面使用多个位置参数吗？

$ node example --arr 1 2
{ _: [], arr: [1, 2] }

如果禁用:

$ node example --arr 1 2
{ _: [2], arr: [1] }

注意:在 v18.0.0 我们正在考虑将贪心数组默认为 false。

Nargs吃期权

默认值: false
关键: nargs-eats-options

应该使用破折号选项以及位置参数。

否定前缀

默认值: no-
关键: negation-prefix

用于被否定的布尔变量的前缀。

$ node example.js --no-foo
{ _: [], foo: false }

如果设置为 quux：

$ node example.js --quuxfoo
{ _: [], foo: false }

填充,

默认值: false。
关键: populate--

是否应该存储未解析的标志 -- 或 _。

如果禁用:

$ node example.js a -b -- x y
{ _: [ 'a', 'x', 'y' ], b: true }

如果启用:

$ node example.js a -b -- x y
{ _: [ 'a' ], '--': [ 'x', 'y' ], b: true }

设置占位符键

默认值: false。
关键: set-placeholder-key。

是否应该为未通过相应的CLI参数设置的键添加占位符？

如果禁用:

$ node example.js -a 1 -c 2
{ _: [], a: 1, c: 2 }

如果启用:

$ node example.js -a 1 -c 2
{ _: [], a: 1, b: undefined, c: 2 }

停止无选择

默认值: false。
关键: halt-at-non-option。

解析应该在第一个位置参数处停止吗？这类似于如何。 ssh 解析其命令行。

如果禁用:

$ node example.js -a run b -x y
{ _: [ 'b' ], a: 'run', x: 'y' }

如果启用:

$ node example.js -a run b -x y
{ _: [ 'b', '-x', 'y' ], a: 'run' }

带别名

默认值: false
关键: strip-aliased

在返回结果之前应该删除别名吗？

如果禁用:

$ node example.js --test-field 1
{ _: [], 'test-field': 1, testField: 1, 'test-alias': 1, testAlias: 1 }

如果启用:

$ node example.js --test-field 1
{ _: [], 'test-field': 1, testField: 1 }

条虚线

默认值: false
关键: strip-dashed

在返回结果之前应该删除虚线键吗？此选项在以下情况下不起作用 camel-case-expansion 是禁用的。

如果禁用:

$ node example.js --test-field 1
{ _: [], 'test-field': 1, testField: 1 }

如果启用:

$ node example.js --test-field 1
{ _: [], testField: 1 }

未知选项作为参数

默认值: false
关键: unknown-options-as-args

未知选项应该像常规参数一样对待吗？未知选项是指不确定的选项中配置 opts。

如果禁用

$ node example.js --unknown-option --known-option 2 --string-option --unknown-option2
{ _: [], unknownOption: true, knownOption: 2, stringOption: '', unknownOption2: true }

如果启用了

$ node example.js --unknown-option --known-option 2 --string-option --unknown-option2
{ _: ['--unknown-option'], knownOption: 2, stringOption: '--unknown-option2' }

支持的Node.js版本

在这个生态系统中，图书馆尽最大努力跟踪 Node.js的发布时间表．这是一个发表我们认为这很重要的原因。

特别感谢

yargs项目从乐观主义者和极简主义者演变而来。它欠它的詹姆斯·韩礼德的辛勤工作谢谢垂直叠加 哔哔声 boop \ o /

许可证

ISC

版本与发布记录

yargs-parser 共发布 84 个版本，首次发布于 2016/01/24；过去 12 个月发布了 0 个版本。

版本	发布日期	距今
`22.0.0`latest	2025/05/27	1.4 年前
`21.1.1`	2022/08/05	4 年前
`21.1.0`	2022/08/04	4 年前
`21.0.1`	2022/02/27	4 年前
`21.0.0`	2021/11/16	4 年前
`20.2.9`	2021/06/21	5 年前

其他发布通道：alpha → 1.1.1-alpha3，latest-13 → 13.1.2，next → 20.2.6，latest-5 → 5.0.1，latest-15 → 15.0.3。

关于 yargs-parser 的常见问题

yargs-parser 是什么？

yargs使用的强大选项解析器

如何安装 yargs-parser？

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

yargs-parser 支持 TypeScript 吗？

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

yargs-parser 支持 ESM 还是 CommonJS？

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

yargs-parser 需要什么版本的 Node.js？

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

yargs-parser 可以商用吗？

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

yargs-parser 的下载量有多少？

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

yargs-parser 还在维护吗？

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

npm install yargs-parser

pnpmpnpm add yargs-parser
yarnyarn add yargs-parser
bunbun add yargs-parser

在你的项目目录中运行此命令。

近 30 天下载

1,110,075,820

约 11.1亿次日均 37,002,527 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，今天更新

最新版本22.0.0发布于 1.4 年前

开源许可ISC宽松许可

包体积85.6 kB10 个文件 · 解压后

运行依赖0 个零依赖

模块格式ES Module

TypeScript未声明类型可查找 @types/yargs-parser

Node.js^20.19.0 || ^22.12.0 || >=23

发布版本84 个近 12 个月 0 个

首次发布2016/01/2410 年前

元数据更新2026/10/31

每一个软件包背后，
都有分享与创造的人。