process.argv en Node.js : arguments en ligne de commande

process.argv est un tableau qui contient la ligne de commande ayant lancé votre programme Node.js. L'indice 0 est le chemin de l'exécutable node, l'indice 1 le chemin de votre script, et vos propres arguments commencent à l'indice 2. Donc process.argv.slice(2) vous donne exactement ce que l'utilisateur a tapé après le nom du fichier, toujours sous forme de chaînes.

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

Les deux premières entrées sont des chemins complets, donc le programme n'affiche que leur dernière partie (node et index.js), puis [ 'Ada', '42', '--verbose' ]. Remplacez la ligne des arguments par Grace 7 et relancez : le tableau suit.

Ce qui entre dans process.argv

Le shell découpe la ligne après node sur les espaces et passe les morceaux à Node.js. Les flags écrits avant le nom du fichier appartiennent à Node.js lui-même, pas à votre programme :

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

Les guillemets regroupent plusieurs mots en un seul argument ("Ada Lovelace" arrive comme une seule chaîne), et le shell remplace les motifs comme *.txt par des noms de fichiers avant même que Node.js ne les voie.

Récupérer les arguments avec slice(2)

La plupart des scripts déstructurent les arguments attendus et donnent une valeur par défaut à chacun :

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

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

Le programme a affiché Hello, Ada : un argument a rempli name, et greeting est revenu à sa valeur par défaut. Ajoutez Hi après Ada dans la ligne des arguments et il affiche Hi, Ada ; videz la ligne et vous obtenez Hello, world.

Les nombres arrivent sous forme de chaînes

Le shell n'a pas de types. Chaque argument est une chaîne, donc les calculs sont faux tant que vous ne convertissez pas :

// $ 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 a concaténé les chaînes en 75, et Number() a donné 12. Un mot qui n'est pas un nombre devient NaN, donc vérifiez avec Number.isNaN et affichez un message d'usage au lieu de continuer avec une valeur cassée.

Parser les flags --name=value à la main

Pour deux ou trois flags, une petite boucle suffit. Celle-ci transforme --port=8080 en port: '8080', un --verbose seul en true, et garde tout le reste comme argument positionnel :

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

Le programme a affiché {"port":"8080","verbose":true} et [ 'build', 'src' ], avec port toujours sous forme de chaîne. Cette boucle ne gère pas les flags courts comme -p ni une valeur dans l'argument suivant (--port 8080) ; pour cela, utilisez le parser intégré ci-dessous.

util.parseArgs, le parser intégré

Node.js 18.3 et suivants fournissent util.parseArgs, qui gère les flags longs et courts, les valeurs dans l'argument suivant, les booléens et les valeurs par défaut :

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 lit process.argv.slice(2) par défaut. Il lève une erreur sur une option non déclarée, ce qui attrape les fautes de frappe comme --prot ; passez strict: false pour accepter les flags inconnus. Les types d'options se limitent à string et boolean, donc les nombres ont toujours besoin de Number(). values est un objet sans prototype, c'est pourquoi il s'affiche avec [Object: null prototype] ; lisez-le comme n'importe quel objet.

Erreurs fréquentes

Lire process.argv[0] comme premier argument. C'est le chemin de node. Votre premier argument est process.argv[2].

Oublier que tout est une chaîne. '10' > '9' vaut false, car les chaînes se comparent caractère par caractère. Convertissez d'abord.

Mettre des secrets dans les arguments. Les lignes de commande apparaissent dans l'historique du shell et dans les listes de processus que les autres utilisateurs de la machine peuvent lire. Passez plutôt les mots de passe et les clés d'API par des variables d'environnement.