yargs — Node.js 命令行参数解析的事实标准

是什么

yargs 是一个 把 process.argv 这串原始字符串数组，翻译成”命令 + 选项 + 位置参数”结构化对象 的 Node.js 库。日常类比：像餐厅前台——客人喊一长串”我要套餐 A 加蛋不要葱外带”，前台把它整理成「主菜=A、加蛋=true、葱=false、形式=外带」交给后厨。

写 Node CLI 工具时，你拿到的 process.argv 长这样：

// node my-cli.js build --watch --port 8080 src/index.ts
// → ['node', 'my-cli.js', 'build', '--watch', '--port', '8080', 'src/index.ts']

你想要的是 { _: ['build'], watch: true, port: 8080, entry: 'src/index.ts' }。yargs 不仅做这一步翻译，还顺带把 --help / --version / shell 自动补全 / 子命令分发 / 配置文件加载全都做完。webpack、mocha、eslint 这些 CLI 的”前台”用的都是它。

为什么重要

不理解 yargs 这层，下面这些事都没法解释：

为什么 webpack --watch --mode=production 这种命令能”自动”显示帮助、版本、错误时给出有用提示
为什么 npm / yarn 的子命令（npm install、yarn add）能嵌套又互不干扰
为什么有的 CLI 你在 zsh 里按 Tab 能自动补全选项名——这能力是免费送的
为什么手撸 process.argv.slice(2) 写过几个 CLI 之后，你最终都会去找一个解析库

核心要点

yargs 的设计可以拆成三层来理解：

解析层（yargs-parser）：纯函数，输入 argv 数组、输出 {_, flags} 对象。处理 - vs --、--key=value vs --key value、-abc 聚合、--no-watch 取反、--config.host=x 嵌套这些边界。这一层独立成包，npm/yarn 只用这一层。
命令层（yargs core）：在解析结果上做命令匹配和分发。.command(name, desc, builder, handler) 注册一条命令；builder 是函数，让子命令的选项懒加载——你不进入这条命令就不解析它的参数。类比：餐厅有 50 个菜单，客人点 A 才翻 A 那一页。
脚手架层（DX）：根据你的 .option() 声明自动生成 --help 帮助、shell completion、版本号、配置文件加载、环境变量映射。同一份”声明”驱动多种产物，不让你重复写。

三层之上是链式 API（.option().command().middleware().parse()），让所有声明和钩子写成一段连贯的代码。

实践案例

案例 1：写一个 build CLI

import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

yargs(hideBin(process.argv))
  .command('build [entry]', '构建项目', (y) => {
    return y
      .positional('entry', { describe: '入口文件', default: 'src/index.ts' })
      .option('watch', { alias: 'w', type: 'boolean', default: false })
      .option('port', { alias: 'p', type: 'number', default: 3000 });
  }, (argv) => {
    runBuild(argv.entry, { watch: argv.watch, port: argv.port });
  })
  .demandCommand(1, '至少需要一个命令')
  .strict()
  .help()
  .parse();

每一行都是一个具体决定，连起来就像在念需求。hideBin 把 node、脚本路径砍掉，只留用户输入。

案例 2：嵌套子命令（git-like）

yargs(hideBin(process.argv))
  .command('config', '配置管理', (y) => {
    return y
      .command('get <key>', '读取配置', () => {}, (argv) => { /* ... */ })
      .command('set <key> <value>', '写入配置', () => {}, (argv) => { /* ... */ })
      .command('list', '列出全部', () => {}, (argv) => { /* ... */ })
      .demandCommand(1);
  })
  .help()
  .parse();

<key> 是必需 positional，[key] 是可选，<key...> 是必需数组。webpack-cli 这种”N 级嵌套”的复杂工具就是这样撑起来的。

案例 3：中间件 + 校验 + 全局错误

yargs(hideBin(process.argv))
  .middleware((argv) => { argv.startTime = Date.now(); })
  .command('serve', '启动服务', /* ... */)
  .check((argv) => {
    if (argv.port < 1024 && process.getuid() !== 0) {
      throw new Error('低位端口需要 root');
    }
    return true;
  })
  .fail((msg, err) => { console.error('错误：', msg || err); process.exit(1); })
  .parse();

middleware / check / fail 三件套对应大型 CLI 的全部生命周期需求：handler 之前跑钩子、handler 之前做校验、出错时统一兜底。

踩过的坑

数字推断丢前导零：--id 0123 默认推成 number 123，前导 0 丢了。要强制保留得 .string('id') 或 .coerce('id', String)。
链式调用顺序有讲究：.help() 必须在 .parse() 之前；.demandCommand() 写在 .strict() 之前能给出更友好的”缺少命令”错误。顺序错了行为就漂移。
嵌套 builder 必须 return y：.command('cfg', '...', (y) => { y.command('get', ...); }) 这样写，get 子命令注册不生效。必须 return y.command('get', ...)，因为 yargs 内部要拿到 builder 的返回值再 merge。
v17 ESM/CJS 双模坑：在 CJS 项目里 require('yargs') 报 require() of ESM，得看 package.json 的 "type" 字段、或换 import 语法。社区有现成的迁移笔记。

适用 vs 不适用场景

适用：

中大型 Node CLI 工具（多子命令、多选项、需要 help/completion 一应俱全）
团队工具脚本（要求声明清晰、可读性高）
想免费拿到配置文件 + 环境变量 + i18n 的项目

不适用：

极简单的脚本（5 个选项以内，手写 process.argv.slice(2) 或用 minimist 就够）
包体积敏感的场景（yargs gzip ~30 KB，commander ~10 KB）
启动速度极致敏感（yargs 多一次”二次 parse”，比 commander 慢 ~3-5ms）
想要类装饰器、强类型路由式 API 的（用 clipanion / oclif）

历史小故事（可跳过）

2010：Ben Coe 从 substack（James Halliday）的 optimist 分叉创建 yargs，因为 optimist 已停滞。
2014：加入 .command() 子命令系统，从”参数解析器”升级为 CLI 框架。
2017：拆出 yargs-parser 子包，让 npm / yarn classic 这种只想要解析层的项目可以独立引入。
2021：v17 大版本——全量改写为 TypeScript，迁移到 ESM + CJS 双模发布。
现在：weekly downloads ~80M，是 webpack-cli、mocha、eslint-cli 等明星工具的事实标准件。

学到什么

声明驱动多产物：一份 .option() 声明同时驱动解析、help 文本、completion 脚本、文档生成。这是好库的标志——别让用户写两遍同一件事。
链式 API 的代价与收益：可读性极强但配置爆炸；小规模 CLI 上读起来像需求文档，大规模时配置项会蔓延到几百行。
懒加载思维：用”builder 是函数”换来”不进入子命令就不解析它”——这种”延迟到真的需要时再展开”的模式在很多框架里出现（React lazy、import() dynamic）。
生态位的力量：yargs 不是最快、不是最小，但它在 2010 年就铺好了 Node CLI 的核心抽象，后续的工具想绕都绕不开。

关联

commander —— Node CLI 解析的另一个主流选择，更声明式、更轻
clack —— 不解析参数但负责交互式 prompt，常和 yargs 一起用
ink —— 用 React 渲染 CLI 输出，yargs 解析后再交给 ink 显示
ora —— CLI 中的 spinner / loading，handler 里跑长任务时配合用
chalk —— CLI 输出着色，yargs 的 help 文本默认就用它
boxen —— CLI 输出加边框，常用于 yargs 应用启动横幅
enquirer —— 命令行交互问答库，和 yargs 形成”参数 + 交互”双层

反向链接

boxen —— boxen — 给终端文本套个边框的事
chalk —— chalk — 让 console.log 输出彩色字符串的 Node 库
clack —— Clack — 给 Common Lisp 加一层标准化的 web 服务器接口
commander —— commander.js — Node.js CLI 解析的声明式标准
enquirer —— enquirer — 让 CLI 工具会问问题的轻量库
ink —— ink — 用 React 组件树写终端 CLI
listr2 —— listr2 — 把 CLI 任务跑成一棵会自己画进度的树
oclif —— oclif — 给 50+ 命令的 CLI 一套”目录即路由”的框架
ora —— ora — 终端 spinner 用 ANSI 反复擦写同一行