process.argv в Node.js: аргументы командной строки

process.argv это массив с командной строкой, которой запустили вашу программу на Node.js. Индекс 0 это путь к исполняемому файлу node, индекс 1 это путь к вашему скрипту, а ваши собственные аргументы начинаются с индекса 2. Поэтому process.argv.slice(2) даёт ровно то, что пользователь ввёл после имени файла, и всегда в виде строк.

// $ node index.js Ada 42 --verbose
const path = require('path');

console.log('argv[0]:', path.basename(process.argv[0]));
console.log('argv[1]:', path.basename(process.argv[1]));
console.log('your arguments:', process.argv.slice(2));

Первые два элемента это полные пути, поэтому программа выводит только их последнюю часть (node и index.js), а затем [ 'Ada', '42', '--verbose' ]. Измените строку аргументов на Grace 7 и запустите снова: массив поменяется следом.

Что попадает в process.argv

Оболочка делит строку после node по пробелам и передаёт Node.js полученные части. Флаги, записанные до имени файла, относятся к самому Node.js, а не к вашей программе:

node --max-old-space-size=4096 index.js --port=8080
# process.argv.slice(2) is [ '--port=8080' ]
# process.execArgv is      [ '--max-old-space-size=4096' ]

Кавычки объединяют слова в один аргумент ("Ada Lovelace" приходит одной строкой), а шаблоны вроде *.txt оболочка раскрывает в имена файлов ещё до того, как их увидит Node.js.

Аргументы через slice(2)

Большинство скриптов деструктурируют ожидаемые аргументы и дают каждому значение по умолчанию:

// $ node index.js Ada
const [name = 'world', greeting = 'Hello'] = process.argv.slice(2);

console.log(`${greeting}, ${name}`);

Программа вывела Hello, Ada: один аргумент заполнил name, а greeting взял значение по умолчанию. Добавьте Hi после Ada в строке аргументов, и она выведет Hi, Ada; очистите строку, и получите Hello, world.

Числа приходят строками

У оболочки нет типов. Каждый аргумент это строка, поэтому арифметика с ними ломается, пока вы их не преобразуете:

// $ node index.js 7 5
const [a, b] = process.argv.slice(2);

console.log('as strings:', a + b);
console.log('as numbers:', Number(a) + Number(b));

const n = Number('ten');
console.log('bad input:', n, Number.isNaN(n));

a + b склеил строки в 75, а Number() дал 12. Слово, которое не является числом, превращается в NaN, поэтому проверяйте через Number.isNaN и выводите подсказку по использованию, а не работайте дальше со сломанным значением.

Разбор флагов --name=value вручную

Для пары флагов хватит короткого цикла. Этот превращает --port=8080 в port: '8080', одиночный --verbose в true, а всё остальное оставляет позиционными аргументами:

// $ node index.js build --port=8080 --verbose src
const flags = {};
const positional = [];

for (const arg of process.argv.slice(2)) {
    if (arg.startsWith('--')) {
        const [key, value = true] = arg.slice(2).split('=');
        flags[key] = value;
    } else {
        positional.push(arg);
    }
}

console.log(JSON.stringify(flags));
console.log(positional);

Программа вывела {"port":"8080","verbose":true} и [ 'build', 'src' ], причём port остался строкой. Этот цикл не понимает короткие флаги вроде -p и значение в следующем аргументе (--port 8080); для этого используйте встроенный парсер ниже.

util.parseArgs, встроенный парсер

В Node.js 18.3 и новее есть util.parseArgs, который понимает длинные и короткие флаги, значения в следующем аргументе, булевы флаги и значения по умолчанию:

const { parseArgs } = require('node:util');

// node index.js -p 8080 --verbose src
const { values, positionals } = parseArgs({
    options: {
        port: { type: 'string', short: 'p', default: '3000' },
        verbose: { type: 'boolean', short: 'v' },
    },
    allowPositionals: true,
});

console.log(values);      // [Object: null prototype] { port: '8080', verbose: true }
console.log(positionals); // [ 'src' ]

По умолчанию parseArgs читает process.argv.slice(2). Он бросает ошибку на опции, которую вы не объявили, и так ловит опечатки вроде --prot; передайте strict: false, чтобы принимать неизвестные флаги. Типы опций бывают только string и boolean, так что числам всё равно нужен Number(). values это объект без прототипа, поэтому он выводится с [Object: null prototype]; читайте его как обычный объект.

Частые ошибки

Считать process.argv[0] первым аргументом. Это путь к node. Ваш первый аргумент это process.argv[2].

Забыть, что всё это строки. '10' > '9' равно false, потому что строки сравниваются посимвольно. Сначала преобразуйте.

Передавать секреты в аргументах. Командные строки попадают в историю оболочки и в списки процессов, которые видят другие пользователи машины. Пароли и API ключи передавайте через переменные окружения.