commander.js 入门指南：构建强大的命令行界面 （全网最全教程）

在Node.js的世界里，创建用户友好的命令行界面（CLI）对于许多应用程序和工具来说至关重要。Commander.js 是一个广受欢迎的 Node.js 包，它为开发者提供了一套简洁而强大的 API，用于快速创建功能完备、用户友好的命令行界面（CLI）应用程序。

一、安装 Commander.js

首先确保您已安装 Node.js 环境。然后，使用 npm（Node Package Manager）轻松安装 Commander.js：

npm install commander

这将在您的项目中添加 commander 依赖项，您可以在项目的 JavaScript 文件中通过 require() 来引入并使用它。

const { program } = require('commander');

// 或者通过创建实例的方式

const { Command } = require('commander');
const program = new Command();

二、基础用法：定义命令与选项

Commander.js 提供了许多方法来帮助你构建功能丰富的命令行应用。以下是一些常用的方法：

1, 在 Commander.js 中，program 代表整个命令行程序的根节点，通过它您可以定义子命令、选项、参数以及执行动作。

program.command(name[, description])：

定义一个新的子命令。name 是子命令的名称，description 是可选的描述。

const subCommand = program.command('sub', 'Sub command description');

program.alias(name)：

为命令或子命令设置一个别名。

program.command('list').alias('ls');

program.description(desc)：

为命令或子命令设置描述。

program.command('clone').description('Clone a repository');

program.version(version[, flags[, description]])：

设置程序的版本信息，并关联一个可选的命令行选项，以便用户查询版本。

// version: (`string`) 程序的版本号。

// optionFlags (`string`, *可选*): 指定显示版本信息的命令行选项，如 `-V, --version`。如果不提供，将默认为 `--version`。

// description (`string`, *可选*): 版本选项在帮助信息中的描述。
program.version('1.2.3', '-v, --version', 'Output the current version');

program.helpOption(flags[, description])：

自定义帮助选项。默认情况下，Commander.js 会添加一个 -h, --help 选项。你可以使用此方法更改帮助选项的名称和描述。

program.helpOption('-i, --info', 'Display help information');

program.option(flags, description, [defaultValue], [fn])

是 Commander.js 中的一个方法，用于定义全局选项，可以定义多个全局选项。。它允许你提供一个短名称、一个长名称、一个描述以及一个可选的处理函数来处理输入的参数值。

// - `flags`：这是一个字符串，包含参数的短名称和长名称。短名称和长名称，中间可以逗号、竖线或空格隔开。例如：`-a, --numberA`。
// - `description`：这是一个字符串，描述了参数的用途。这个描述将在命令行应用的帮助信息中显示。
// - `defaultValue`（可选）：这是参数的默认值。如果用户没有提供参数值，将使用此默认值。
// - `fn`（可选）：这是一个函数，用于处理输入的参数值。例如，你可以使用 `parseInt` 或 `parseFloat` 函数将输入的字符串转换为数字。如果未提供此函数，参数值将作为字符串处理。

program
  .option("-d, --debug", "是否开启调试模式", false)
  // -e/--env后跟的字符，将存到envName属性中
  .option("-e, --envName <envName>", "获取环境变量名称", 'production');

获取选项键值对
使用opts()获取解析命令行参数后的选项键值对，属性名为选项的长标识

const opts = program.opts();
console.log(opts) // => {debug: false, envName: 'production'}

program.parse(process.argv)

// 这行代码是用来解析命令行参数的，它将会读取 process.argv 数组中的参数，并根据定义的命令和选项来执行相应的操作。

// 其中，process.argv 是一个包含命令行参数的数组，
// 第一个元素是 Node.js 的可执行文件路径，
// 第二个元素是当前执行的 JavaScript 文件路径，
// 之后的元素是传递给脚本的参数。
process.argv [
  '/Users/nolan/.nvm/versions/node/v20.12.1/bin/node',
  '/Users/nolan/Desktop/zustand-cli/src/index.js',
  'zustand',
  'new'
]
// program.parse(process.argv) 将会解析这些参数并执行对应的命令。

// argv(`string[]`, 默认: `process.argv.slice(2)`): 要解析的命令行参数数组。通常不需要传递，直接使用默认值即可。

program.parse(process.argv);

三、实战演练：创建一个简单的文件查找器

创建一个简单的命令行应用

我们将创建一个简单的命令行应用，用于计算两个数字的和。首先，创建一个名为 addition-cli.js 的文件，并引入 Commander.js：

const { program } = require('commander');

接下来，我们需要定义我们的命令行参数。在这个例子中，我们需要两个数字参数。我们将使用 option 方法来定义这些参数：

program
  .option('-a, --numberA <value>', 'First number', parseFloat)
  .option('-b, --numberB <value>', 'Second number', parseFloat);

option 方法接受三个参数：

1. 参数的短名称（如 -a）和长名称（如 --numberA）
2. 参数的描述
3. 可选的参数处理函数。在这个例子中，我们使用 parseFloat 将输入的字符串转换为浮点数。

现在，我们需要处理这些参数，并执行相应的操作。我们将使用 action 方法来实现这一点：

program.action(() => {
  const { numberA, numberB } = program.opts();

  if (numberA === undefined || numberB === undefined) {
    console.error('Both numbers must be provided');
    process.exit(1);
  }

  const result = numberA + numberB;
  console.log(`The sum of ${numberA} and ${numberB} is ${result}`);
});

program.opts() 会返回一个包含所有命令行参数的对象。我们从该对象中提取 numberA 和 numberB，然后计算它们的和，并将结果输出到控制台。

最后，我们需要调用 program.parse() 方法来解析命令行参数：

program.parse(process.argv);

现在，我们的 addition-cli.js 文件应该如下所示：

#!/usr/bin/env node

const { program } = require('commander');

program
  .option('-a, --numberA <value>', 'First number', parseFloat)
  .option('-b, --numberB <value>', 'Second number', parseFloat);

program.action(() => {
  const { numberA, numberB } = program.opts();

  if (numberA === undefined || numberB === undefined) {
    console.error('Both numbers must be provided');
    process.exit(1);
  }

  const result = numberA + numberB;
  console.log(`The sum of ${numberA} and ${numberB} is ${result}`);
});

program.parse(process.argv);

测试我们的命令行应用

现在，我们可以通过运行以下命令来测试我们的命令行应用：

node addition-cli.js -a 3.2 -b 4.8

输出应该如下所示：

The sum of 3.2 and 4.8 is 8

总结

在本文中，我们学习了如何使用 Commander.js 创建一个简单的命令行应用。我们通过一个实际的例子介绍了如何定义和处理命令行参数。当然，Commander.js 还有许多其他功能，如子命令、自定义帮助信息等，你可以在 Commander.js 官方文档 中找到更多信息。