Node.js / 系统课时

解析命令行参数

解析命令行参数

命令行工具要先把“用户输入了什么”变成程序能稳定使用的数据。本课用 Node.js 自带的 process.argv 和 node:util 的 parseArgs(),解析命令名称、位置参数、字符串选项和布尔开关,并补上缺参校验,让后续文件操作只接收已经整理好的输入。

学习目标

  • 识别 process.argv 中运行时参数与用户参数的边界。
  • 使用 parseArgs() 解析命令、位置参数、短选项和布尔选项。
  • 对未知命令和缺失参数给出明确错误,而不是把错误输入传到业务逻辑。

先看清 process.argv 的位置

Node.js 启动脚本时,process.argv[0] 是 Node 可执行文件路径,process.argv[1] 是当前脚本路径,真正由用户输入的内容从索引 2 开始。因此手写解析时通常先取 process.argv.slice(2),不要把前两个运行时路径误当成业务参数。

新建 args-inspect.mjs:

js
const userArgs = process.argv.slice(2);

// 只观察用户实际输入的参数,避免被 Node 和脚本路径干扰。
console.log(userArgs);

运行:

bash
node args-inspect.mjs organize ./downloads --dry-run

预期输出:

text
[ 'organize', './downloads', '--dry-run' ]

这里可以把 organize 当成命令名称,把 ./downloads 当成位置参数,把 --dry-run 当成开关。参数一多,继续靠数组下标手工判断会很快变得难维护,此时应交给结构化解析器。

用 parseArgs 定义选项规则

Node.js 22 及以上可直接使用稳定的 parseArgs()。下面把第一个位置参数定义为命令名,第二个定义为源目录;-o 或 --output 接收字符串,--dry-run 只表示开或关。allowPositionals: true 必须开启,否则位置参数会被拒绝。

新建 cli.mjs:

js
import { parseArgs } from 'node:util';

const { values, positionals } = parseArgs({
  options: {
    output: { type: 'string', short: 'o' },
    'dry-run': { type: 'boolean' },
  },
  allowPositionals: true,
});

const [command, source] = positionals;

if (command !== 'organize') {
  console.error('用法: node cli.mjs organize <source> [-o <dir>] [--dry-run]');
  process.exitCode = 1;
} else if (!source) {
  console.error('错误: 缺少 source 目录');
  process.exitCode = 1;
} else {
  const parsed = {
    command,
    source,
    output: values.output ?? './organized',
    dryRun: values['dry-run'] ?? false,
  };

  console.log(JSON.stringify(parsed, null, 2));
}

运行:

bash
node cli.mjs organize ./downloads -o ./sorted --dry-run

预期输出:

json
{
  "command": "organize",
  "source": "./downloads",
  "output": "./sorted",
  "dryRun": true
}

type: 'string' 要求选项后提供值,所以 -o ./sorted 合法;type: 'boolean' 不需要再写 true。短选项 -o 与长选项 --output 会落到同一个 values.output 字段。

在进入业务逻辑前完成校验

参数解析成功不代表输入一定可用。命令名、必填位置参数和取值范围应该在文件读写之前检查,这样错误会停在入口层。上面的示例用 process.exitCode = 1 标记失败,同时保留明确的用法提示。

运行缺少源目录的命令:

bash
node cli.mjs organize

预期输出:

text
错误: 缺少 source 目录

再运行未知命令:

bash
node cli.mjs clean ./downloads

预期输出:

text
用法: node cli.mjs organize <source> [-o <dir>] [--dry-run]

实际项目还应继续验证路径是否存在、是否为目录,以及 output 是否允许写入。一个实用边界是:命令行层只负责把输入解析并校验成稳定对象,真正的文件整理函数不要再次猜测 process.argv 的位置和含义。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

解析命令行参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通