Node.js parseArgs 重复选项：传了两次 mode，为什么结果只保留最后一次
维护一个命令行工具时，用户可能同时传入 --mode=fast 和 --mode safe。解析没有报错，values.mode 却只剩 safe。要判断是否误写了两次，就不能仅检查最终 values；需要保留原始选项出现的记录。
util.parseArgs 的 multiple 开关决定重复选项是收集成数组，还是采用最后一个值。tokens 则保存解析位置等信息，可以用于增加“某选项只能出现一次”的业务规则。下面不读取实际命令行，而是直接传入固定 args，保证每次运行都能重现同一组输入。
本例在 Node.js v24.19.0 实跑。parseArgs 自 Node.js 20.0.0 起不再是实验API，本文以 Node.js 24 环境验证。把完整代码保存为 demo.mjs，执行 node demo.mjs；没有文件写入、网络请求或外部命令。
AI模型生成概念插图：参数序列分别进入保留最后值与收集多值的容器，下方轨迹表示出现位置；图中卡片数量为概念比喻，不是程序数据截图。
完整实验程序
import assert from 'node:assert/strict';
import { parseArgs } from 'node:util';
const args = ['--mode=fast', '--mode', 'safe',
'--tag', 'red', '-tblue', '--', '--mode=ignored'];
const options = {
mode: { type: 'string' },
tag: { type: 'string', short: 't', multiple: true }
};
const result = parseArgs({ args, options, tokens: true,
strict: true, allowPositionals: true });
assert.equal(result.values.mode, 'safe');
assert.deepEqual(result.values.tag, ['red', 'blue']);
assert.deepEqual(result.positionals, ['--mode=ignored']);
console.log('values', JSON.stringify(result.values));
console.log('positionals', JSON.stringify(result.positionals));
const modes = result.tokens.filter(token =>
token.kind === 'option' && token.name === 'mode');
console.log('mode tokens', JSON.stringify(modes.map(token => ({
index: token.index, value: token.value, inlineValue: token.inlineValue
}))));
function requireSingle(name, tokens) {
const found = tokens.filter(token =>
token.kind === 'option' && token.name === name);
if (found.length > 1) throw new Error(`duplicate --${name}`);
}
assert.throws(() => requireSingle('mode', result.tokens), /duplicate --mode/);
console.log('duplicate check', 'rejected');
try {
parseArgs({ args: ['--moed', 'safe'], options, strict: true });
} catch (error) {
assert.equal(error.code, 'ERR_PARSE_ARGS_UNKNOWN_OPTION');
console.log('unknown option', error.code);
}本地实际输出
values {"mode":"safe","tag":["red","blue"]}
positionals ["--mode=ignored"]
mode tokens [{"index":0,"value":"fast","inlineValue":true},{"index":1,"value":"safe","inlineValue":false}]
duplicate check rejected
unknown option ERR_PARSE_ARGS_UNKNOWN_OPTION最终值和输入历史是两份信息
values 里的 mode 是 safe，tag 是按出现顺序排列的 red、blue。mode 没有打开 multiple，因此采用最后值；tag 显式允许多值，所以长选项 --tag 和短选项 -t 的值都保留下来。一个选项能重复出现，不意味着所有选项都应使用同一种合并办法。
mode tokens 显示两个记录，index 分别为零和一。位置按 args 数组计数；第二个值 safe 自己占据索引二，但它属于索引一的 --mode，因此token的index不是值的位置。inlineValue 的 true、false 区分等号内联形式与独立的后续参数。
requireSingle 根据规范化后的 token.name 计数，看到两次 mode 后明确拒绝。它检查的是输入历史，不会被最后值覆盖掩盖。在实际工具里，可以把重复位置带进错误提示，帮助使用者检查脚本拼接或配置展开是否重复附加了选项。
双横线之后要按位置参数理解
输入里的 -- 把后面的 --mode=ignored 留在 positionals 中，因此它没有覆盖 mode。本文显式打开 allowPositionals；业务若不接收位置参数，应维持对应约束，而不是把无法解释的输入静默忽略。
最后一个拼错的 --moed 在 strict 模式下得到 ERR_PARSE_ARGS_UNKNOWN_OPTION。这个检查与前面的重复检查不同：解析器认识 mode，不会因此自动替你拒绝它出现两次。语法层面合法之后，仍需要工具自己的约束。
字符串选项的结果仍是字符串。若以后增加重试次数或端口号，应在解析后验证数值格式和范围；不要因为参数进入了 values 就认为它已经是可用业务值。保留固定args测试，分别覆盖重复、空值、未知选项和结束标记，能让命令行接口的变化有清楚的回归依据。
参考资料
官方资料核验日期：2026-10-02。以上输出来自文中完整程序，断言通过，退出状态为零。
