À propos de ce cours
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 :
| Valeur | Poste du développeur | Tests automatiques | Serveur de production |
|---|---|---|---|
| Port | 3000 | aléatoire | 8080 (derrière Nginx) |
| Base de données | localhost, formation_dev | formation_test, vidée à chaque test | serveur dédié, formation |
| Mot de passe | simple | simple | secret, connu de l'administrateur seulement |
| Niveau de journal | debug | error | log |
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
- Tout est texte.
process.env.PORTvaut"4000", pas4000."30" + 1donne"301". TypeScript le signale d'ailleurs : le type eststring | undefined, et l'addition avec une valeur possiblementundefinedest refusée en mode strict (le!a été ajouté pour forcer la compilation). - « false » est vrai.
DEBUG=falsedonne la chaîne"false", non vide, donc vraie dans unif. Il faut comparer :process.env.DEBUG === 'true'. - Une variable absente vaut
undefined, etNumber(undefined)donneNaN. 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
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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !