Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Les variables d'environnement et le fichier .env

Cette leçon explique pourquoi la configuration d'une API (port, base de données, clés secrètes) ne doit pas être écrite dans le code, et comment Node.js la lit dans les variables d'environnement avec ...

0 chapitres 0 QCM Accès gratuit
Les variables d'environnement et le fichier .env

À propos de ce cours

Cette leçon explique pourquoi la configuration d'une API (port, base de données, clés secrètes) ne doit pas être écrite dans le code, et comment Node.js la lit dans les variables d'environnement avec process.env. Des programmes exécutés montrent les trois pièges classiques (tout est texte, la chaîne false est vraie, une variable absente vaut undefined) et leur correction. La leçon présente ensuite le fichier .env, sa syntaxe, sa lecture avec dotenv ou nativement avec Node.js 22, la priorité entre les sources, et les règles de sécurité : .gitignore, .env.example et secrets jamais versionnés. Activités corrigées.

Objectifs de la leçon

  • Expliquer pourquoi la configuration ne doit pas être écrite dans le code.
  • Lire et convertir correctement les variables d'environnement avec process.env.
  • Écrire et charger un fichier .env.
  • Connaître la priorité entre les différentes sources.
  • Protéger les secrets : .gitignore et .env.example.
Le problème : une configuration écrite dans le code

Jusqu'ici, nos API écrivaient en dur le port (3000), des valeurs métier (MAX_TACHES = 100) et même des clés API (TP 6). Au chapitre 11, il faudra ajouter l'adresse et le mot de passe de la base de données. Or ces valeurs changent selon l'endroit où l'application tourne :

ValeurPoste du développeurTests automatiquesServeur de production
Port3000aléatoire8080 (derrière Nginx)
Base de donnéeslocalhost, formation_devformation_test, vidée à chaque testserveur dédié, formation
Mot de passesimplesimplesecret, connu de l'administrateur seulement
Niveau de journaldebugerrorlog

Modifier le code avant chaque déploiement serait source d'erreurs, et un mot de passe écrit dans le code finit tôt ou tard sur GitHub. La règle, issue de la méthode des Twelve-Factor Apps: le même code partout, la configuration dans l'environnement.

process.env

Chaque programme reçoit du système une liste de variables d'environnement (nom = valeur). En Node.js, elles sont dans l'objet process.env. On peut en définir pour une seule exécution, devant la commande (Linux, macOS, Git Bash) :

PORT=4000 DEBUG=false node dist/main.js

# PowerShell (Windows)
$env:PORT="4000"; node dist/main.js

📄 src/main.ts

// src/main.ts : lire des variables d'environnement avec Node.js seul
const port = process.env.PORT;
const debug = process.env.DEBUG;
const maxStagiaires = process.env.MAX_STAGIAIRES;

console.log('PORT          =', JSON.stringify(port), '→ type', typeof port);
console.log('DEBUG         =', JSON.stringify(debug));
console.log('MAX_STAGIAIRES=', JSON.stringify(maxStagiaires));

// Piège 1 : tout est texte (le « ! » fait taire TypeScript, qui signalait le risque)
console.log('MAX + 1       =', maxStagiaires! + 1);
// Piège 2 : la chaîne "false" est « vraie »
console.log('debug activé ?', debug ? 'oui' : 'non');
// Piège 3 : une variable absente vaut undefined
console.log('max * 2       =', Number(maxStagiaires) * 2);

// La bonne façon : convertir et donner une valeur par défaut
const portOk = Number(process.env.PORT ?? 3000);
const debugOk = process.env.DEBUG === 'true';
const maxOk = Number.parseInt(process.env.MAX_STAGIAIRES ?? '30', 10);
console.log('converti      =', { portOk, debugOk, maxOk });

Résultat réellement obtenu :

$ node dist/main.js
PORT          = undefined → type undefined
DEBUG         = undefined
MAX_STAGIAIRES= undefined
MAX + 1       = NaN
debug activé ? non
max * 2       = NaN
converti      = { portOk: 3000, debugOk: false, maxOk: 30 }

$ PORT=4000 DEBUG=false MAX_STAGIAIRES=30 node dist/main.js
PORT          = "4000" → type string
DEBUG         = "false"
MAX_STAGIAIRES= "30"
MAX + 1       = 301
debug activé ? oui
max * 2       = 60
converti      = { portOk: 4000, debugOk: false, maxOk: 30 }
Les trois pièges
  1. Tout est texte. process.env.PORT vaut "4000", pas 4000. "30" + 1 donne "301". TypeScript le signale d'ailleurs : le type est string | undefined, et l'addition avec une valeur possiblement undefined est refusée en mode strict (le ! a été ajouté pour forcer la compilation).
  2. « false » est vrai. DEBUG=false donne la chaîne "false", non vide, donc vraie dans un if. Il faut comparer : process.env.DEBUG === 'true'.
  3. Une variable absente vaut undefined, et Number(undefined) donne NaN. Il faut une valeur par défaut avec ??.

Retenez: toute variable d'environnement doit être convertie (nombre, booléen) et avoir une valeur par défaut ou être déclarée obligatoire. La leçon 10.3 automatise ces trois règles.

Le fichier .env

Taper toutes les variables à chaque lancement n'est pas pratique en développement. On les regroupe dans un fichier .env à la racine du projet :

📄 .env

# .env : configuration locale de développement (NE PAS versionner)
PORT=3000
NODE_ENV=development

# Base de données
DB_HOTE=localhost
DB_PORT=3306
DB_UTILISATEUR=apc_dev
DB_MOT_DE_PASSE="m0t de p@sse # avec dièse"
DB_NOM=formation_dev

# Valeurs diverses
MAX_STAGIAIRES=30

Règles de syntaxe :

  • une variable par ligne, NOM=valeur, sans espace autour du =;
  • les lignes commençant par # sont des commentaires ;
  • les guillemets sont nécessaires si la valeur contient des espaces ou un # (sinon la suite serait prise pour un commentaire) ;
  • par convention, les noms sont en MAJUSCULES, avec un préfixe par domaine (DB_, JWT_, MAIL_).
Charger le fichier .env

Node.js ne lit pas ce fichier tout seul. Première solution, la bibliothèque dotenv (c'est elle que @nestjs/config utilise en interne, leçon 10.2) :

npm install dotenv

📄 src/main.ts

// Lecture d'un fichier .env avec dotenv
import 'dotenv/config';                       // charge .env dans process.env au démarrage

const cles = ['PORT', 'NODE_ENV', 'DB_HOTE', 'DB_PORT', 'DB_MOT_DE_PASSE', 'MAX_STAGIAIRES'];
for (const cle of cles) {
  console.log(cle.padEnd(16), '=', JSON.stringify(process.env[cle]));
}

Résultat réellement obtenu :

$ node dist/main.js
PORT             = "3000"
NODE_ENV         = "development"
DB_HOTE          = "localhost"
DB_PORT          = "3306"
DB_MOT_DE_PASSE  = "m0t de p@sse # avec dièse"
MAX_STAGIAIRES   = "30"

$ PORT=8080 node dist/main.js   (variable réelle déjà définie)
PORT             = "8080"
NODE_ENV         = "development"
DB_HOTE          = "localhost"
DB_PORT          = "3306"
DB_MOT_DE_PASSE  = "m0t de p@sse # avec dièse"
MAX_STAGIAIRES   = "30"

La seconde exécution montre la priorité: PORT=8080, déjà défini quand le programme démarre, n'est pas écrasé par le PORT=3000 du fichier. C'est voulu : en production, les variables définies sur le serveur l'emportent toujours sur un fichier oublié.

Deuxième solution, sans aucune bibliothèque : depuis Node.js 20.12 (et donc Node.js 22), le support est intégré.

📄 src/main.ts

// Sans aucune bibliothèque : Node.js 20.12+ / 22 sait lire un fichier .env
process.loadEnvFile('.env');                  // ou : node --env-file=.env dist/main.js
console.log('DB_NOM =', process.env.DB_NOM, '| PORT =', process.env.PORT);

Résultat réellement obtenu :

$ node dist/main.js
DB_NOM = formation_dev | PORT = 3000

Sources et priorité des variables d'environnement

Toutes les sources aboutissent dans process.env, sous forme de texte.

Protéger les secrets

Le fichier .env contient des mots de passe : il ne doit jamais être versionné. Le .gitignore généré par nest new contient déjà les lignes nécessaires ; vérifiez-le :

📄 .gitignore (extrait)

# dotenv environment variable files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local

Pour que vos collègues (et vos étudiants) sachent quelles variables définir, on versionne un fichier .env.example: mêmes noms, valeurs d'exemple ou vides pour les secrets.

📄 .env.example

# .env.example : modèle VERSIONNÉ, à copier en .env puis à compléter
PORT=3000
NODE_ENV=development

DB_HOTE=localhost
DB_PORT=3306
DB_UTILISATEUR=
DB_MOT_DE_PASSE=
DB_NOM=formation_dev

MAX_STAGIAIRES=30
cp .env.example .env      # première installation du projet, puis compléter .env

Si un secret a été poussé par erreur sur GitHub, le supprimer dans un nouveau commit ne suffit pas : il reste dans l'historique, et des robots parcourent GitHub en permanence à la recherche de clés. Il faut changer le secret (nouveau mot de passe, nouvelle clé) immédiatement. GitHub peut aussi bloquer certains secrets à l'envoi (push protection).

Activités

Activité 1 Repérer la configuration

Dans votre projet du TP 6 (api-formation-securisee), listez toutes les valeurs qui devraient venir de l'environnement. Pour chacune, proposez un nom de variable, une valeur par défaut éventuelle, et indiquez si c'est un secret.

Voir le corrigé

Par exemple : PORT (3000, non secret) ; NODE_ENV (development) ; CLES_API (aucune valeur par défaut, secret) ; CORS_ORIGINES (http://localhost:4200) ; DELAI_MAX_MS (5000) ; NIVEAU_JOURNAL (log). Les valeurs métier qui ne changent pas selon l'environnement (liste des niveaux de formation) restent dans le code.

Activité 2 Convertir correctement

Écrivez une petite fonction lireEntier(nom, defaut) et une fonction lireBooleen(nom, defaut) qui lisent une variable d'environnement, la convertissent et lèvent une erreur explicite si la valeur est présente mais invalide (PORT=abc, DEBUG=peut-etre).

Voir le corrigé
export function lireEntier(nom: string, defaut: number): number {
  const brut = process.env[nom];
  if (brut === undefined || brut === '') return defaut;
  const n = Number(brut);
  if (!Number.isInteger(n)) throw new Error(`La variable ${nom} doit être un entier (reçu : « ${brut} »)`);
  return n;
}

export function lireBooleen(nom: string, defaut: boolean): boolean {
  const brut = process.env[nom]?.toLowerCase();
  if (brut === undefined || brut === '') return defaut;
  if (['true', '1', 'oui'].includes(brut)) return true;
  if (['false', '0', 'non'].includes(brut)) return false;
  throw new Error(`La variable ${nom} doit valoir true ou false (reçu : « ${brut} »)`);
}

Ces fonctions font à la main ce que la validation de la leçon 10.3 fera de façon déclarative.

Activité 3 Priorité

Le fichier .env contient PORT=3000. Quel port utilise l'application dans chaque cas ? (a) node dist/main.js; (b) PORT=5000 node dist/main.js; (c) export PORT=6000 puis node dist/main.js; (d) le fichier contient PORT= (vide) et le code fait process.env.PORT ?? 3000.

Voir le corrigé

(a) 3000. (b) 5000 : la variable de la commande l'emporte. (c) 6000 : la variable est définie dans le terminal pour toutes les commandes suivantes. (d) Piège : la variable existe et vaut la chaîne vide "", et ?? ne remplace que null et undefined. Le port vaut donc "". Il faut écrire process.env.PORT || 3000 ou, mieux, valider la configuration (leçon 10.3).

Activité 4 Préparer le dépôt

Dans api-formation-securisee: créez .env et .env.example, vérifiez avec git status que .env n'apparaît pas, puis faites un commit « chore: modèle de configuration .env.example ». Que se passe-t-il si .env avait déjà été commité auparavant ?

Voir le corrigé

.gitignore n'agit que sur les fichiers non suivis. Un fichier déjà commité reste suivi : il faut l'en retirer avec git rm --cached .env, faire un commit, et changer les secrets qu'il contenait, puisqu'ils sont dans l'historique.

À retenir

  • La configuration qui change selon l'environnement (port, base, secrets) sort du code.
  • process.env contient des chaînes ou undefined : convertir et prévoir une valeur par défaut.
  • DEBUG=false donne la chaîne "false", qui est vraie : comparer avec === 'true'.
  • Le fichier .env se charge avec dotenv ou nativement (process.loadEnvFile, --env-file).
  • Une variable déjà définie l'emporte sur le fichier .env.
  • .env dans .gitignore, .env.example versionné ; un secret publié doit être changé.

Cet article vous a-t-il aidé ?