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:
const userArgs = process.argv.slice(2);
// 只观察用户实际输入的参数,避免被 Node 和脚本路径干扰。
console.log(userArgs);运行:
node args-inspect.mjs organize ./downloads --dry-run预期输出:
[ 'organize', './downloads', '--dry-run' ]这里可以把 organize 当成命令名称,把 ./downloads 当成位置参数,把 --dry-run 当成开关。参数一多,继续靠数组下标手工判断会很快变得难维护,此时应交给结构化解析器。
用 parseArgs 定义选项规则
Node.js 22 及以上可直接使用稳定的 parseArgs()。下面把第一个位置参数定义为命令名,第二个定义为源目录;-o 或 --output 接收字符串,--dry-run 只表示开或关。allowPositionals: true 必须开启,否则位置参数会被拒绝。
新建 cli.mjs:
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));
}运行:
node cli.mjs organize ./downloads -o ./sorted --dry-run预期输出:
{
"command": "organize",
"source": "./downloads",
"output": "./sorted",
"dryRun": true
}type: 'string' 要求选项后提供值,所以 -o ./sorted 合法;type: 'boolean' 不需要再写 true。短选项 -o 与长选项 --output 会落到同一个 values.output 字段。
在进入业务逻辑前完成校验
参数解析成功不代表输入一定可用。命令名、必填位置参数和取值范围应该在文件读写之前检查,这样错误会停在入口层。上面的示例用 process.exitCode = 1 标记失败,同时保留明确的用法提示。
运行缺少源目录的命令:
node cli.mjs organize预期输出:
错误: 缺少 source 目录再运行未知命令:
node cli.mjs clean ./downloads预期输出:
用法: node cli.mjs organize <source> [-o <dir>] [--dry-run]实际项目还应继续验证路径是否存在、是否为目录,以及 output 是否允许写入。一个实用边界是:命令行层只负责把输入解析并校验成稳定对象,真正的文件整理函数不要再次猜测 process.argv 的位置和含义。