如何正确使用 yargs 定义和触发命令行子命令

如何正确使用 yargs 定义和触发命令行子命令 — yargs 不触发命令通常是因为命令定义与调用方式不匹配：`command(‘name ‘)` 表示位置参数（非 flag），而 `–flag` 形式需在 builder 函数中显式声明选项；混淆二者会导致解析失败并默认显示帮助页。

在使用 yargs 构建 CLI 工具时，一个常见误区是将命令参数误写为 –add-item 或直接混用短横线命令名与 flag 风格调用（如 node script.js –add-item 1 2）。yargs 的 .command() 方法不支持以 –xxx 开头的命令名，且其语法结构严格区分「命令名」「位置参数」和「选项（flags）」三类元素。

✅ 正确用法：命令 + 选项（推荐用于可读性与健壮性）

若希望支持类似 node my_script.js add-item –val1=3 –val2=55 的调用方式，应将参数定义在 builder 对象中（即第二个参数），而非嵌入命令字符串：

import yargs from 'yargs'; import { hideBin } from 'yargs/helpers';  void yargs(hideBin(process.argv))   .command(     'add-item', // ← 命令名（无短横线）     'Add a new item with two values',     (yargs) => yargs       .option('val1', {         type: 'string',         demand: true,         describe: 'The first value (required)',       })       .option('val2', {         type: 'number',         demand: true,         describe: 'The second value (required, numeric)',       }),     async (argv) => {       console.log('✅ add-item executed:', { val1: argv.val1, val2: argv.val2 });       // 实际业务逻辑...     }   )   .command(     'print',     'Print a value',     (yargs) => yargs       .option('val1', {         type: 'string',         demand: true,         describe: 'Value to print',       }),     async (argv) => {       console.log('?️  print executed:', argv.val1);     }   )   .demandCommand(1, '⚠️  Please specify a command: add-item or print')   .help()   .alias('help', 'h')   .parse();

✅ 调用示例：

node my_script.js add-item --val1="hello" --val2=42 node my_script.js print --val1="world"

? 提示：.option() 自动支持缩写（如 .alias(‘v’, ‘val1’)）、类型校验、必填约束（demand: true）及自动帮助文案生成。

⚠️ 错误模式解析

• ❌ command(‘–add-item ‘)：yargs 将 –add-item 视为非法命令名（含 -），直接忽略该命令注册；
• ❌ command(‘add-item ‘) + node script.js add-item 1 2：此时 v1 和 v2 是位置参数，必须紧随命令名之后、无 — 前缀；但若同时传入其他 flag（如 –debug），它们不会被自动挂载到 argv 中，除非额外调用 .options()；
• ❌ node script.js –add-item 1 2：–add-item 被解析为全局 flag（未定义），yargs 找不到匹配命令，回退至 .help()。

? 补充：纯位置参数模式（仅限简单场景）

若坚持使用位置参数（如 node script.js add-item apple 123），需确保命令定义与调用完全对齐：

.command(   'add-item  ',   'Add item by name and ID',   {}, // builder 留空或仅配置全局选项   async (argv) => {     console.log('?', argv.item, 'ID:', argv.id);   } )

调用：

node my_script.js add-item "My Item" 999

⚠️ 注意：此时 argv.item 和 argv.id 类型默认为 String，需手动转换；且无法混合使用 –xxx 标志（除非在全局层定义）。

✅ 最佳实践总结

遵循以上规范，即可彻底解决 yargs “命令不触发、只显示 help” 的问题，构建出专业、可靠、易维护的 node.js CLI 工具。