Configurer les variables d'environnement Node.js

Une application a besoin de valeurs qui changent selon l'environnement : port, URL de base de données, jeton d'API, clé de signature. Les écrire dans le code oblige à modifier le code pour chaque déploiement et expose les secrets dans Git. Les variables d'environnement séparent la configuration du programme : la plateforme les injecte au démarrage, votre code les lit.

Lire une variable

process.env contient les variables fournies par l'environnement et la plateforme. Attention, tout y est une chaîne de caractères, même un nombre.

const port = Number(process.env.PORT);
if (!Number.isInteger(port) || port <= 0) {
  console.error("PORT manquant ou invalide");
  process.exit(1);
}

Validez au démarrage plutôt qu'au premier usage. Une application qui s'arrête tout de suite avec un message clair est plus facile à diagnostiquer qu'une erreur 500 survenue trois heures plus tard.

const dbUrl = process.env.DATABASE_URL;
if (!dbUrl) {
  console.error("DATABASE_URL manquante");
  process.exit(1);
}

N'utilisez de valeur par défaut que pour des paramètres non sensibles, comme un port de développement local. Jamais pour un mot de passe, un jeton ou une URL de production.

Définir les variables dans le panneau

Dans le service d'hébergement d'applications, ouvrez les réglages puis la section des variables d'environnement. Ajoutez une paire nom/valeur par ligne :

DATABASE_URL = mysql://utilisateur:[email protected]:3306/base
API_TOKEN = remplacez-par-un-jeton
NODE_ENV = production

Deux points à connaître : le processus ne relit pas les variables à chaud, il faut redémarrer le service après une modification ; et toute personne ayant accès au panneau peut voir les valeurs. Ne partagez pas le compte et ne collez pas de secret durable dans un champ que vous oubliez de nettoyer.

En local avec un fichier .env

En développement, un fichier .env à la racine du projet évite de redéfinir les variables à chaque commande. Node.js 20.6 et versions suivantes savent le lire directement :

node --env-file=.env index.js

Le fichier ressemble à ceci :

PORT=3000
NODE_ENV=development
DATABASE_URL=mysql://utilisateur:[email protected]:3306/base

Sur Node.js 18, qui ne connaît pas cette option, chargez plutôt un module comme dotenv au début du fichier principal.

Ajoutez .env à .gitignore et versionnez un .env.example qui ne contient que les noms et des valeurs factices. C'est le seul moyen simple d'éviter qu'un secret finisse dans l'historique Git, où il reste même après suppression du fichier.

Bonnes pratiques

• Ne journalisez jamais process.env en entier : la sortie finit souvent dans les logs de la plateforme.
• Un secret exposé doit être remplacé, pas seulement retiré du code.
• Séparez les valeurs de développement et de production ; ne réutilisez pas le même jeton.
• Validez le type et la présence de chaque variable critique au démarrage.
• Utilisez des noms explicites : DATABASE_URL, API_TOKEN, SESSION_SECRET.
• Ne mettez pas de guillemets autour des valeurs dans le panneau, ils feraient partie de la valeur.

Une variable bien nommée et validée vaut mieux qu'un fichier de configuration commenté que personne ne lit.