yargs 未知参数 — CLI 拒绝合法标志

症状

遇到“yargs 未知参数 — CLI 拒绝合法标志”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• CLI 打印 “Unknown arguments: long-flag, longFlag” 后退出
• 升级后原本可用的标志开始报错
• –flag=true 被拒绝，而 –flag true 可用

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

node cli.js deploy --env=prod

错误会列出所有未知 token，可据此直接对应到缺失的 .option() 声明。

步骤 2

node -e "const y=require('yargs/yargs')(['node','x']); console.log(y.option('env').getOptions())"

确认选项及其别名是否存在；添加 alias 以同时接受两种写法。

常见诱因（按出现频率排序）：

• 启用了 strict()，但标志未在命令构建器中声明
• 选项以连字符命名，用户却传驼峰（或反之），且未设别名
• 布尔选项用 = 赋值，而解析器期望空格分隔形式

根因

yargs 的 strict() 一旦遇到未声明的 token 就中止运行。连字符与驼峰写法在未设别名时彼此独立，因此声明了 –dry-run 的严格模式不会自动接受 –dryRun。

修复

声明所有预期标志，为常见的不同拼写添加别名，并把 .strict() 与 .demandCommand() 搭配使用，让拼写错误明确失败而非被忽略。对于透传数据，可调整 .parserConfiguration 或有选择地 .strict(false)。

注意：全局关闭严格模式会把拼写错误变成被静默忽略的标志，在 CI 中比硬失败更糟。

#!/usr/bin/env node
import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

yargs(hideBin(process.argv))
  .command('deploy', 'deploy the app', (y) =>
    y.option('env', { type: 'string', alias: 'e', choices: ['dev', 'prod'], demandOption: true })
     .option('dry-run', { type: 'boolean', alias: 'dryRun' }),
  )
  .strict()
  .demandCommand(1)
  .parse();

验证

重跑此前失败的调用并确认可解析；再故意传入错误拼写的标志，确认仍会失败，证明严格性未被削弱。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。