commander.js开发CLI工具参数解析异常：子命令与选项识别问题

开发的CLI工具通过Commander.js配置了capture和list-devices子命令，但执行capture命令时参数解析异常，无法正确识别子命令及对应选项、参数。

原配置脚本 #

import { Command, Option } from "commander";

function parseArguments() {
  const program = new Command();

  program
    .name('video-recorder')
    .description('Video recorder utility capturing screen & sound output')

  program.command("list-devices").description("Lists devices");

  program
    .command("capture")
    .addOption(
      new Option("-p --profile <profile>", "Profile to use to record")
        .default(undefined),
    )
    .addOption(
      new Option(
        "-d --duration <time>",
        "Duration of the video, in format [HH:]mm:ss",
      )
    )
    .argument("<url>", "url to the page of the video")
    .argument("<path>", "path to output to");

  program.parse(process.argv);
  return program;
}

async function main() {
  const program = parseArguments();
  const [url, outpath] = program.args;
    const args = {
      url: url,
      outpath: outpath,
      ... program.opts(),
    };
    console.log(args)
  // ...
}

main();

执行命令及错误输出 #

执行命令：

node src/main.js capture -p abc -d '9:48' 'https://www.example.com/video-id' '/path/to/output_file.mp4'

得到错误输出：

{ url: 'capture', outpath: '-p' }

问题原因 #

直接通过根命令program的args和opts()获取数据是错误的，子命令的参数、选项属于子命令实例，根命令的args只会捕获未被子命令处理的内容，导致解析逻辑混乱。

修复方案 #

修改代码逻辑，定位到当前执行的子命令实例，再从该实例获取对应的参数和选项：

修改后的完整代码 #

import { Command, Option } from "commander";

function parseArguments() {
  const program = new Command();

  program
    .name('video-recorder')
    .description('Video recorder utility capturing screen & sound output')

  program.command("list-devices").description("Lists devices");

  program
    .command("capture")
    .addOption(
      new Option("-p --profile <profile>", "Profile to use to record")
        .default(undefined),
    )
    .addOption(
      new Option(
        "-d --duration <time>",
        "Duration of the video, in format [HH:]mm:ss",
      )
    )
    .argument("<url>", "url to the page of the video")
    .argument("<path>", "path to output to");

  program.parse(process.argv);
  return program;
}

async function main() {
  const program = parseArguments();
  // 获取当前执行的子命令实例
  const subCommand = program.commands.find(cmd => cmd.name() === program.args[0]);
  
  if (subCommand) {
    // 根据子命令类型处理参数
    if (subCommand.name() === 'capture') {
      // capture子命令的参数和选项
      const [url, outpath] = subCommand.args;
      const args = {
        url,
        outpath,
        ...subCommand.opts()
      };
      console.log(args);
      // 后续业务逻辑
    } else if (subCommand.name() === 'list-devices') {
      // list-devices命令的处理逻辑
      console.log('Listing devices...');
    }
  }
}

main();

修复说明 #

• 通过program.commands遍历子命令，结合program.args[0]定位到当前执行的子命令实例
• 从子命令实例的args和opts()中获取对应的参数与选项，避免根命令和子命令的数据混淆
• 可根据子命令名称分支处理不同的业务逻辑

执行原命令后，将得到正确输出：

{ url: 'https://www.example.com/video-id', outpath: '/path/to/output_file.mp4', profile: 'abc', duration: '9:48' }

内容的提问来源于stack exchange，提问作者Philippe Hebert