npargv 参数解析器

一个轻量级的 Node.js 扩展，用于快速、灵活地解析 process.argv 命令行参数。支持类型校验、默认值填充、子命令解析及严格模式。

安装

npm i npargv

快速上手

'use strict'

const parseArgv = require('npargv')

// 1. 定义参数规则 (Schema)
const schema = {
  // 基础定义：指定类型和范围
  '--port=': {
    name: 'port',
    alias: '-p',      // 别名支持
    type: 'int',
    min: 2000,
    max: 9000
  },

  // 正则匹配
  '--host=': {
    name: 'host',
    match: /^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$/i,
    default: '127.0.0.1'
  },

  // 简写模式：自动推断为 boolean，name 为 'verbose'
  '-v': 'verbose',

  // 简写模式：自动推断为 boolean，name 为 '-x'
  '-x': null,

  // 回调函数处理
  '--ids': {
    name: 'ids',
    callback: (str) => str.split(',').filter(x => x.length > 0)
  },

  // 位置参数引用 ($1 表示第一个非命令参数)
  '$1': {
    name: 'inputFile',
    type: 'string'
  }
}

// 2. 解析配置 (Options)
const options = {
  strict: true,       // 遇到错误是否立即停止并返回失败
  autoDefault: true,  // 是否自动填充默认值
  commands: ['start', 'build'], // 支持的子命令
  defaultCommand: 'start'       // 默认子命令
}

// 3. 执行解析
const ret = parseArgv(schema, options)

console.log(ret)

运行命令：

$ node app.js start --port=8080 -v --ids=1,2,3 config.json

输出结果：

{
  ok: true,           // 解析是否成功
  message: '',        // 如果失败，返回第一个错误信息
  errors: [],         // 所有错误信息的数组
  command: 'start',   // 解析到的子命令
  args: {             // 解析后的参数对象
    port: 8080,
    host: '127.0.0.1', // 使用了默认值
    verbose: true,
    '-x': false,       // 默认值
    ids: ['1', '2', '3'],
    inputFile: 'config.json'
  },
  list: []            // 未定义的非 Flag 参数（如多余的文件名）
}

核心功能详解

1. 返回值说明

解析函数返回一个对象，包含以下字段：

| 字段 | 类型 | 描述 | | :--- | :--- | :--- | | ok | boolean | 解析是否成功。在 strict: true 模式下，有任何错误即为 false。 | | message | string | 错误提示信息（兼容旧版 errmsg），若无错误为空字符串。 | | errors | array | 包含解析过程中产生的所有错误信息的数组。 | | args | object | 解析后的键值对结果。 | | command | string | 识别到的子命令（若配置了 commands）。 | | list | array | 未被定义的普通参数（不以 - 开头的内容，或被转义的内容）。 |

注意：根据最新代码逻辑，未定义的 Flag 参数（以 - 开头但未在 Schema 中定义的参数）会被忽略，不会出现在 args 或 list 中。

2. 参数定义 (Schema)

schema 对象中的 Key 通常是命令行参数的触发标识（如 --port 或 --port=），Value 是配置对象。

配置项支持

| 选项 | 类型 | 描述 | | :--- | :--- | :--- | | type | string | 数据类型。支持 int/number, float, string, bool/boolean。若未指定，会尝试自动推断。 | | name | string | 解析结果 args 中的属性名。 | | alias | string | 参数别名，例如 -p 指向 --port。 | | default | any | 默认值。若解析出错（且非严格模式）或未输入，则使用此值。 | | min | number | 最小值限制（仅对数字类型有效）。 | | max | number | 最大值限制（仅对数字类型有效）。 | | match | RegExp | 正则表达式校验（会自动将 type 推断为 string）。 | | callback | function | 自定义处理函数。接收原始值，若返回非 undefined，则替换解析值。 |

简写模式

• 字符串简写：{ '-v': 'verbose' } 等价于 { '-v': { name: 'verbose', type: 'boolean', default: false } }
• 空简写：{ '--flag': null } 或 { '--flag': {} } 等价于 { '--flag': { name: '--flag', type: 'boolean' } }

类型推断规则 (Type Inference)

若未显式指定 type，程序按以下顺序自动推断：

1. 若 Key 包含 = (如 --port=)，推断为 string。
2. 若配置了 match 或 callback，推断为 string。
3. 若配置了 min 或 max，推断为 int。
4. 若配置了 default，推断为 default 值的类型。
5. 默认推断为 boolean。

3. 解析选项 (Options)

parseArgv 的第二个参数用于控制解析行为：

parseArgv(schema, {
  strict: true,        // 严格模式 (默认 true)
  autoDefault: true,   // 自动生成默认值 (默认 true)
  commands: [],        // 子命令列表
  defaultCommand: '',  // 缺省子命令
  argv: process.argv   // 自定义参数源 (用于测试或非 node 环境)
})

strict 严格模式

• true (默认)：一旦遇到类型错误、范围错误或缺少必要参数，立即停止解析，ok 返回 false，并返回错误信息。
• false：遇到错误时会将错误推入 errors 数组，但不会中断解析。出错的参数将保留其默认值（如果有），解析继续进行。

autoDefault 自动默认值

开启后，程序会根据 type 自动填充 default 值（仅在 schema 中未定义 default 时生效）：

• number/int/float: 默认为 min (若存在) 或 0。
• string: 默认为 '' (空字符串)。
• bool: 默认为 false。

4. 子命令支持

通过配置 commands 数组启用子命令模式。

let options = {
  commands: ['create', 'delete', 'update'],
  defaultCommand: 'create'
}

• 解析逻辑：程序会检查脚本后的第一个参数。如果是 commands 列表中的一项，则将其记录在返回对象的 command 字段中，并从下一个参数开始解析 Flag。
• 位置参数影响：若使用了子命令，位置参数 $1 指向子命令之后的第一个参数。

5. 位置引用参数 ($1, $2...)

支持直接解析固定位置的参数。Key 使用 $N 格式（N 从 1 开始）。

const schema = {
  // $1 是第一个非 Flag 参数
  '$1': { name: 'source', type: 'string' },
  // $2 是第二个
  '$2': { name: 'dest', type: 'string' }
}

• 注意：$N 对应的是实际参数列表中的顺序。如果启用了子命令，$1 是子命令后的第一个参数。

6. 转义与未知参数

• 转义：如果需要传递以 - 开头的普通字符串（例如文件名名为 -file），可以使用 \ 转义，如 \-file。解析器会将其还原为 -file 并放入 list 数组中。
• 未知参数：不以 - 开头的参数，如果未被位置引用（$N）捕获，会被放入 list 数组。

常见示例

场景：Web 服务器配置

const schema = {
  // 端口：整数，2000-9000，默认 3000
  '--port': { type: 'int', min: 2000, max: 9000, default: 3000 },
  
  // 开启调试：布尔值
  '--debug': 'debug',
  
  // 数据库地址：正则校验
  '--db': { match: /^mysql:\/\//, name: 'databaseUrl' }
};

const result = parseArgv(schema, { strict: true });

if (!result.ok) {
  console.error('参数错误:', result.message);
  process.exit(1);
}

console.log('启动服务:', result.args);

场景：文件处理工具 (非严格模式)

const schema = {
  '$1': { name: 'file' },
  '--retry': { type: 'int', default: 3 }
};

// strict: false 允许参数出错时不中断，使用默认值
const result = parseArgv(schema, { strict: false });

if (result.errors.length > 0) {
  console.warn('警告：部分参数不合法，已使用默认值:', result.errors);
}

// 即使 --retry=abc 输入错误，args.retry 仍为 3
runProcess(result.args);