Node.js process.argv: Kommandozeilenargumente lesen

process.argv ist ein Array mit der Kommandozeile, die dein Node.js-Programm gestartet hat. Index 0 ist der Pfad zur Programmdatei node, Index 1 der Pfad zu deinem Skript, und deine eigenen Argumente beginnen bei Index 2. process.argv.slice(2) gibt dir also genau das, was der Nutzer nach dem Dateinamen eingegeben hat, immer als Strings.

// $ 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));

Die ersten beiden Einträge sind vollständige Pfade, deshalb gibt das Beispiel nur ihren letzten Teil aus (node und index.js), dann [ 'Ada', '42', '--verbose' ]. Ändere die Argumentzeile in Grace 7 und führ es noch einmal aus: Das Array zieht mit.

Was in process.argv landet

Die Shell teilt die Zeile nach node an Leerzeichen und gibt Node.js die Teile. Flags vor dem Dateinamen gehören zu Node.js selbst, nicht zu deinem Programm:

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' ]

Anführungszeichen fassen Wörter zu einem Argument zusammen ("Ada Lovelace" kommt als ein einziger String an), und die Shell erweitert Muster wie *.txt zu Dateinamen, bevor Node.js sie überhaupt sieht.

Die Argumente mit slice(2) holen

Die meisten Skripte zerlegen die erwarteten Argumente per Destructuring und geben jedem einen Standardwert:

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

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

Es hat Hello, Ada ausgegeben: Ein Argument hat name gefüllt, und greeting ist auf seinen Standardwert zurückgefallen. Füg in der Argumentzeile Hi nach Ada hinzu, und es gibt Hi, Ada aus; leere die Zeile, und du bekommst Hello, world.

Zahlen kommen als Strings an

Die Shell kennt keine Typen. Jedes Argument ist ein String, Rechnen damit geht also schief, bis du umwandelst:

// $ 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 hat die Strings zu 75 verbunden, und Number() hat 12 ergeben. Ein Wort, das keine Zahl ist, wird zu NaN, prüf also mit Number.isNaN und gib eine Benutzungshilfe aus, statt mit einem kaputten Wert weiterzumachen.

--name=value-Flags von Hand parsen

Für ein paar Flags reicht eine kurze Schleife. Diese macht aus --port=8080 port: '8080', aus einem einzelnen --verbose true und behält alles andere als Positionsargument:

// $ 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);

Es hat {"port":"8080","verbose":true} und [ 'build', 'src' ] ausgegeben, wobei port noch ein String ist. Diese Schleife kann keine kurzen Flags wie -p und keinen Wert im nächsten Argument (--port 8080); dafür nimm den eingebauten Parser unten.

util.parseArgs, der eingebaute Parser

Node.js 18.3 und neuer bringen util.parseArgs mit, das lange und kurze Flags, Werte im nächsten Argument, Booleans und Standardwerte behandelt:

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 liest standardmäßig process.argv.slice(2). Es wirft bei einer Option, die du nicht deklariert hast, und fängt so Tippfehler wie --prot; übergib strict: false, um unbekannte Flags zu akzeptieren. Als Optionstypen gibt es nur string und boolean, Zahlen brauchen also weiterhin Number(). values ist ein Objekt ohne Prototyp, deshalb erscheint es mit [Object: null prototype]; lies es wie jedes Objekt.

Häufige Fehler

process.argv[0] als erstes Argument lesen. Das ist der Pfad zu node. Dein erstes Argument ist process.argv[2].

Vergessen, dass alles ein String ist. '10' > '9' ist false, weil Strings Zeichen für Zeichen verglichen werden. Wandle zuerst um.

Geheimnisse in Argumente packen. Kommandozeilen landen in der Shell-History und in Prozesslisten, die andere Nutzer auf dem Rechner lesen können. Übergib Passwörter und API-Keys stattdessen über Umgebungsvariablen.