Commander.js is the most popular command-line interface (CLI) framework for Node.js. — Commander.js 是 Node.js 中最受欢迎的命令行接口（CLI）框架。

Commander.js 触发场景 快速创建 CLI 脚手架 定义选项和参数 创建子命令 自定义帮助信息 TypeScript 支持 快速开始 // 1. 安装 npm install commander // 2. 创建 CLI const { Command } = require('commander'); const program = new Command(); program .name('my-cli') .description('我的 CLI 工具') .version('1.0.0'); program.parse();

选项定义 基本选项类型 // 布尔选项（无参数） program.option('-d, --debug', '启用调试模式'); // 值选项（需要参数） program.option('-p, --port ', '服务器端口', '3000'); // 可选值选项 program.option('--cheese [type]', '添加奶酪（可选类型）'); // 否定布尔选项 program.option('--no-sauce', '不需要酱料'); // 必需选项 program.requiredOption('-c, --cheese ', '必须选择一种奶酪类型'); // 可变参数选项（数组） program.option('--items ', '多个项目');

访问选项值 const options = program.opts(); console.log(options.debug); // 或 program.opts().debug // 驼峰命名转换：--template-engine → opts().templateEngine

自定义选项处理 program.option('--date ', '日期', (value) => new Date(value));

子命令 内联子命令 program.command('serve') .description('启动服务器') .option('-p, --port ') .action((options) => { console.log('服务器运行在端口', options.port); }); program.command('build') .description('构建项目') .option('--watch') .action((options) => { console.log('构建中...'); });

独立可执行子命令 // 主程序 program.command('git hooks', { isDefault: true }); // 子命令文件：commands/git-hook.js #!/usr/bin/env node console.log('运行 git hook');

参数定义 必需参数 program.argument('', '输入文件'); // 可选参数 program.argument('[file]', '输入文件（可选）'); // 可变参数 program.argument('', '多个文件'); // 在操作处理程序中访问 program.command('split') .argument('', '要拆分的字符串') .option('--separator ', '分隔符', ',') .action((str, options) => { console.log(str.split(options.separator)); });

帮助系统 自动帮助 node app.js --help node app.js help 命令

自定义帮助 program.on('option:help', () => { console.log('自定义帮助信息'); program.help(); }); program.addHelpCommand(false); // 禁用帮助子命令

全局对象快捷方式 对于简单的脚本，可以使用全局对象： const { program } = require('commander'); program .name('my-tool') .option('-v, --verbose') .action(() => { console.log(program.opts().verbose ? '详细模式' : '正常模式'); }); program.parse();

TypeScript 支持 import { Command } from 'commander'; const program = new Command(); program .name('ts-cli') .option('-n, --name ', '名称') .action((options) => { console.log('你好', options.name); }); program.parse();

常见配置 配置解析行为 program.configureOutput({ writeErr: (str) => process.stderr.write(str), outputWidth: 80, }); // 启用冲突检查 program.allowUnknownOption(); program.passThroughOptions(); // 生命周期钩子 program .hook('preAction', (thisCommand) => { console.log('预操作钩子'); }) .hook('postAction', (thisCommand) => { console.log('操作后钩子'); });

最佳实践 使用本地 Command 对象（而不是全局对象）以便于单元测试 始终调用 program.parse() 以开始解析 更喜欢 .option() 而不是直接处理 process.argv 使用 camelCase 选项名称以进行自动转换：--template-engine → opts().templateEngine 使用 .description() 提供清晰的帮助信息