Yargs 命令行参数解析工具 API 详解

Yargs 命令行参数解析工具 API 详解

yargs 项目地址: https://gitcode.com/gh_mirrors/yar/yargs

Yargs 是一个强大的 Node.js 命令行参数解析工具，它能够帮助开发者轻松处理命令行输入，构建复杂的命令行界面。本文将深入解析 Yargs 的核心 API，帮助开发者更好地掌握这个工具的使用方法。

基础解析功能

Yargs 最基本的功能是将命令行参数解析为一个对象。它可以直接处理 process.argv 参数：

require('yargs/yargs')(process.argv.slice(2)).parse()

也可以手动传入参数数组：

require('yargs/yargs')(['-x', '1', '-y', '2']).parse()

需要注意的是，当从 process.argv 获取参数时，应该使用 process.argv.slice(2) 来跳过 Node.js 自动添加的前两个参数。

Yargs 还提供了 hideBin 辅助函数来简化这一过程：

const { hideBin } = require('yargs/helpers')
const argv = yargs(hideBin(process.argv)).parse()

参数类型处理

数组类型参数

使用 .array(key) 方法可以将参数解析为数组：

.option('ingredients', {
  alias: 'i',
  describe: '添加食材',
  array: true
})

这样 --ingredients apple banana 将被解析为 ['apple', 'banana']。

布尔类型参数

.boolean(key) 方法将参数标记为布尔类型：

.boolean('verbose')

使用 --no-verbose 可以显式设置为 false。

枚举值限制

.choices(key, choices) 方法可以限制参数只能接受特定的值：

.choices('size', ['small', 'medium', 'large'])

参数验证与转换

参数验证

.check(fn) 方法允许对参数进行验证：

.check((argv) => {
  if (argv.x > 10 && argv.y < 5) {
    throw new Error('x不能大于10且y不能小于5')
  }
  return true
})

值转换

.coerce(key, fn) 方法可以对参数值进行转换：

.coerce('file', async (path) => {
  const content = await fs.readFile(path, 'utf8')
  return JSON.parse(content)
})

命令系统

Yargs 提供了强大的命令系统，可以构建复杂的 CLI 应用。

基本命令定义

.command('get <url>', '发起GET请求', (yargs) => {
  yargs.positional('url', {
    describe: '请求的URL'
  })
}, (argv) => {
  console.log(`正在请求: ${argv.url}`)
})

命令目录加载

.commandDir(directory) 可以从目录加载命令模块：

.commandDir('commands', {
  recurse: true,
  extensions: ['js']
})

配置管理

JSON 配置文件

.config() 方法支持从 JSON 文件加载配置：

.config('config', '配置文件路径', (configPath) => {
  return JSON.parse(fs.readFileSync(configPath))
})

配置继承

支持使用 extends 关键字继承其他配置：

.config({
  extends: './base-config.json',
  logLevel: 'debug'
})

高级功能

自动补全

.completion() 方法可以生成 bash/zsh 自动补全脚本：

.completion('completion', (current, argv) => {
  return ['init', 'build', 'test']
})

参数冲突检测

.conflicts(x, y) 可以检测参数冲突：

.conflicts('verbose', 'silent')

计数参数

.count(key) 将参数视为计数器：

.count('verbose')
// --verbose --verbose → verbose: 2

默认值与必填参数

默认值设置

.default('port', 3000, '默认端口号')

必填参数

.demandOption(['host', 'port'], '必须提供host和port参数')

总结

Yargs 提供了丰富的 API 来处理命令行参数，从简单的参数解析到复杂的命令系统构建，都能轻松应对。通过本文的介绍，开发者可以掌握 Yargs 的核心功能，构建出更加专业和易用的命令行工具。

yargs 项目地址: https://gitcode.com/gh_mirrors/yar/yargs