# yargs-parser 中文文档规范地址：https://npmcn.com/package/yargs-parser/ 版本：22\.0\.0 npm 元数据更新时间：2026-10-31T05:24:18.801Z 中文译文更新时间：2026-11-04T12:30:20.528Z 软件包许可：ISC 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。原始 npm 页面：https://www.npmjs.com/package/yargs-parser 原文对照：https://npmcn.com/package/yargs-parser/?lang=original 项目主页：https://github.com/yargs/yargs-parser#readme 源码仓库：https://github.com/yargs/yargs-parser ## 关键信息（来自 npm 元数据） - 包体积（解压后）：85.6 kB，10 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：^20\.19\.0 \|\| ^22\.12\.0 \|\| \>=23 - 运行依赖：0 个 - 首次发布：2016-01-23T21:12:29.644Z - 最新版本发布：2025-05-26T20:12:00.864Z - 近 30 天下载量：1110075820（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：84（近 12 个月 0 个） ## 中文简介 yargs使用的强大选项解析器 ## 安装 ```sh npm install yargs-parser ``` 也可以使用：`pnpm add yargs-parser`、`yarn add yargs-parser`、`bun add yargs-parser` ## README # yargs-parser ![ci](https://github.com/yargs/yargs-parser/workflows/ci/badge.svg) [![NPM version](https://img.shields.io/npm/v/yargs-parser.svg)](https://www.npmjs.com/package/yargs-parser) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org/) ![nycrc config on GitHub](https://img.shields.io/nycrc/yargs/yargs-parser) 的强大选项解析器 [yargs](https://github.com/yargs/yargs)。参观 [yargs网站](http://yargs.js.org/) 有关更多示例，以及详细的使用说明。 ![](https://raw.githubusercontent.com/yargs/yargs-parser/main/yargs-logo.png) ## 例子 ```sh npm i yargs-parser --save ``` ```js const argv = require('yargs-parser')(process.argv.slice(2)) console.log(argv) ``` ```console $ node example.js --foo=33 --bar hello { _: [], foo: 33, bar: 'hello' } ``` _或者解析字符串！_ ```js const argv = require('yargs-parser')('--foo=99 --bar=33') console.log(argv) ``` ```console { _: [], foo: 99, bar: 33 } ``` 类型之前转换混合类型的数组 `yargs-parser`： ```js 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](https://github.com/denoland/deno)： ```typescript 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:** ```js import parser from 'yargs-parser' const argv = parser('--foo=99 --bar=9987930', { string: ['bar'] }) console.log(argv) ``` **浏览器:** ```html ``` ## 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解析器提供配置选项(参见： [配置](https://npmcn.com/package/yargs-parser/#readme-configuration)）. - `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`。 ```js var parsed = parser(['--no-dice'], { configuration: { 'boolean-negation': false } }) ``` ### 空头期权组 - 默认值: `true`。 - 关键: `short-option-groups`。一组短选项应该被视为布尔标志吗？ ```console $ node example.js -abc { _: [], a: true, b: true, c: true } ``` _如果禁用:_ ```console $ node example.js -abc { _: [], abc: true } ``` ### “骆峰式”扩张 - 默认值: `true`。 - 关键: `camel-case-expansion`。用连字符连接的参数是否应该扩展为驼峰式别名？ ```console $ node example.js --foo-bar { _: [], 'foo-bar': true, fooBar: true } ``` _如果禁用:_ ```console $ node example.js --foo-bar { _: [], 'foo-bar': true } ``` ### 通过点 - 默认值: `true` - 关键: `dot-notation` 应该键包含 `.` 被当作物品对待？ ```console $ node example.js --foo.bar { _: [], foo: { bar: true } } ``` _如果禁用:_ ```console $ node example.js --foo.bar { _: [], "foo.bar": true } ``` ### 解析数据 - 默认值: `true` - 关键: `parse-numbers` 看起来像数字的键应该被这样对待吗？ ```console $ node example.js --foo=99.3 { _: [], foo: 99.3 } ``` _如果禁用:_ ```console $ node example.js --foo=99.3 { _: [], foo: "99.3" } ``` ### 解析位置数字 - 默认值: `true` - 关键: `parse-positional-numbers` 看起来像数字的位置键是否应该被这样对待？ ```console $ node example.js 99.3 { _: [99.3] } ``` _如果禁用:_ ```console $ node example.js 99.3 { _: ['99.3'] } ``` ### 布尔否定 - 默认值: `true` - 关键: `boolean-negation` 变量的前缀应该是 `--no` 被视为否定？ ```console $ node example.js --no-foo { _: [], foo: false } ``` _如果禁用:_ ```console $ node example.js --no-foo { _: [], "no-foo": true } ``` ### 结合数组 - 默认值: `false` - 关键: `combine-arrays` 当由命令行参数和配置文件。 ### 重复参数数组 - 默认值: `true` - 关键: `duplicate-arguments-array` 当参数重复时，是否应该将其强制转换为数组： ```console $ node example.js -x 1 -x 2 { _: [], x: [1, 2] } ``` _如果禁用:_ ```console $ node example.js -x 1 -x 2 { _: [], x: 2 } ``` ### 平放重复数组 - 默认值: `true` - 关键: `flatten-duplicate-arrays` 当数组参数重复时，应该强制转换为单个数组吗？ ```console $ node example.js -x 1 2 -x 3 4 { _: [], x: [1, 2, 3, 4] } ``` _如果禁用:_ ```console $ node example.js -x 1 2 -x 3 4 { _: [], x: [[1, 2], [3, 4]] } ``` ### 贪婪的数组 - 默认值: `true` - 关键: `greedy-arrays` 数组应该在其标志后面使用多个位置参数吗？ ```console $ node example --arr 1 2 { _: [], arr: [1, 2] } ``` _如果禁用:_ ```console $ node example --arr 1 2 { _: [2], arr: [1] } ``` **注意:在 `v18.0.0` 我们正在考虑将贪心数组默认为 `false`。** ### Nargs吃期权 - 默认值: `false` - 关键: `nargs-eats-options` 应该使用破折号选项以及位置参数。 ### 否定前缀 - 默认值: `no-` - 关键: `negation-prefix` 用于被否定的布尔变量的前缀。 ```console $ node example.js --no-foo { _: [], foo: false } ``` _如果设置为 `quux`：_ ```console $ node example.js --quuxfoo { _: [], foo: false } ``` ### 填充, - 默认值: `false`。 - 关键: `populate--` 是否应该存储未解析的标志 `--` 或 `_`。 _如果禁用:_ ```console $ node example.js a -b -- x y { _: [ 'a', 'x', 'y' ], b: true } ``` _如果启用:_ ```console $ node example.js a -b -- x y { _: [ 'a' ], '--': [ 'x', 'y' ], b: true } ``` ### 设置占位符键 - 默认值: `false`。 - 关键: `set-placeholder-key`。是否应该为未通过相应的CLI参数设置的键添加占位符？ _如果禁用:_ ```console $ node example.js -a 1 -c 2 { _: [], a: 1, c: 2 } ``` _如果启用:_ ```console $ node example.js -a 1 -c 2 { _: [], a: 1, b: undefined, c: 2 } ``` ### 停止无选择 - 默认值: `false`。 - 关键: `halt-at-non-option`。解析应该在第一个位置参数处停止吗？这类似于如何。 `ssh` 解析其命令行。 _如果禁用:_ ```console $ node example.js -a run b -x y { _: [ 'b' ], a: 'run', x: 'y' } ``` _如果启用:_ ```console $ node example.js -a run b -x y { _: [ 'b', '-x', 'y' ], a: 'run' } ``` ### 带别名 - 默认值: `false` - 关键: `strip-aliased` 在返回结果之前应该删除别名吗？ _如果禁用:_ ```console $ node example.js --test-field 1 { _: [], 'test-field': 1, testField: 1, 'test-alias': 1, testAlias: 1 } ``` _如果启用:_ ```console $ node example.js --test-field 1 { _: [], 'test-field': 1, testField: 1 } ``` ### 条虚线 - 默认值: `false` - 关键: `strip-dashed` 在返回结果之前应该删除虚线键吗？此选项在以下情况下不起作用 `camel-case-expansion` 是禁用的。 _如果禁用:_ ```console $ node example.js --test-field 1 { _: [], 'test-field': 1, testField: 1 } ``` _如果启用:_ ```console $ node example.js --test-field 1 { _: [], testField: 1 } ``` ### 未知选项作为参数 - 默认值: `false` - 关键: `unknown-options-as-args` 未知选项应该像常规参数一样对待吗？未知选项是指不确定的选项中配置 `opts`。 _如果禁用_ ```console $ node example.js --unknown-option --known-option 2 --string-option --unknown-option2 { _: [], unknownOption: true, knownOption: 2, stringOption: '', unknownOption2: true } ``` _如果启用了_ ```console $ node example.js --unknown-option --known-option 2 --string-option --unknown-option2 { _: ['--unknown-option'], knownOption: 2, stringOption: '--unknown-option2' } ``` ## 支持的Node.js版本在这个生态系统中，图书馆尽最大努力跟踪 [Node.js的发布时间表](https://nodejs.org/en/about/releases/)．这是 [一个发表我们认为这很重要的原因](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a)。 ## 特别感谢 yargs项目从乐观主义者和极简主义者演变而来。它欠它的詹姆斯·韩礼德的辛勤工作谢谢 [垂直叠加](https://github.com/substack) **哔哔声** **boop** \\ o / ## 许可证 ISC ## 常见问题 ### 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 和提交记录判断。