Un fichier .env, concrètement
Un fichier .env ne contient ni programme ni données d'utilisateurs : c'est une liste de réglages, un par ligne, sous la forme NOM=valeur. On y range ce qui change d'une machine à l'autre ou qui ne doit pas apparaître dans le code source : l'adresse d'une base de données, une clé d'API, un mot de passe SMTP, le port d'un serveur, un drapeau DEBUG.
Le nom lui-même est trompeur pour qui n'a jamais vu de projet web. Le fichier s'appelle littéralement .env, sans rien avant le point. Ce n'est pas une extension rattachée à un nom (comme photo.jpg) : c'est un nom complet qui commence par un point. Sur Linux et macOS, cette convention rend le fichier invisible par défaut dans le Finder ou un ls simple, ce qui explique qu'on le cherche souvent sans le trouver.
Au démarrage, le programme lit ce fichier et transforme chaque ligne en variable d'environnement, accessible ensuite par son nom (process.env.PORT en JavaScript, os.environ["PORT"] en Python). Le code reste identique sur le poste du développeur et sur le serveur ; seul le .env diffère.
Un exemple minimal tient en quatre lignes : une ligne de commentaire « # Réglages locaux », puis PORT=3000, DATABASE_URL="postgres://localhost:5432/boutique" et API_KEY=remplacer-par-la-vraie-cle. Chaque ligne crée une variable ; le commentaire est ignoré.
La syntaxe d'un fichier .env, ligne par ligne
Il n'existe pas de norme officielle unique : chaque bibliothèque a ses tolérances. La documentation de Node.js, qui lit désormais ces fichiers sans module externe, publie toutefois des règles précises qui servent de bon repère.
Noms de variables
Un nom commence par une lettre ou un tiret bas, puis ne contient que des lettres, des chiffres et des tirets bas. MY_VAR, my_var_1 ou myVar passent ; 1_VAR (chiffre en tête), my-var (tiret) ou VAR_#1 (dièse) sont refusés. L'usage le plus répandu reste les majuscules séparées par des tirets bas, qui distinguent d'un coup d'œil ces réglages des variables ordinaires du code.
Valeurs, guillemets et lignes multiples
La valeur se place après le signe égal, avec ou sans guillemets simples ou doubles. Les espaces en début et en fin de clé et de valeur sont ignorés, sauf à l'intérieur des guillemets. Une valeur sans guillemets tient sur une seule ligne ; pour une clé privée ou un certificat qui s'étale sur plusieurs lignes, les guillemets deviennent obligatoires.
Point souvent mal compris : tout est du texte. PORT=3000 donne la chaîne '3000', DEBUG=true donne 'true' et RETRIES=0 donne '0'. Le code doit donc convertir lui-même en nombre ou en booléen ; sinon, un test du genre « si DEBUG » sera vrai même quand la valeur vaut false, puisqu'une chaîne non vide est considérée comme vraie en JavaScript.
Commentaires et préfixe export
Un # placé hors guillemets ouvre un commentaire jusqu'à la fin de la ligne. Entre guillemets, en revanche, il redevient un caractère normal : MOT_DE_PASSE="ab#12" conserve bien le dièse. Le préfixe export en début de ligne est accepté puis ignoré par Node.js, ce qui permet de charger le même fichier directement dans un terminal Bash avec source .env.
| Ligne écrite | Résultat |
|---|---|
| PORT=3000 | variable PORT, valeur texte « 3000 » |
| export MODE=prod | accepté, le mot export est ignoré |
| CLE="a#b" | le dièse fait partie de la valeur |
| CLE=a #note | valeur « a », la suite est un commentaire |
| 1_VAR=x | refusé : un nom ne commence pas par un chiffre |
| my-var=x | refusé : tiret interdit dans le nom |
Comment un programme charge son .env
Le système d'exploitation ne lit jamais ce fichier tout seul. Il faut qu'un outil le charge avant ou pendant le démarrage de l'application.
En Node.js, sans dépendance
Pendant des années, la seule méthode courante passait par le paquet npm dotenv et un appel à require('dotenv').config() en tête du programme. Node.js propose aujourd'hui ses propres outils, décrits dans sa documentation. L'option de ligne de commande --env-file charge le fichier au lancement, par exemple « node --env-file=.env app.js ». Sa variante --env-file-if-exists ne bloque pas le démarrage si le fichier manque, ce qui sert quand la production fournit ses variables autrement. Depuis le code, la fonction process.loadEnvFile() fait le même travail, tandis que util.parseEnv() transforme le contenu d'un fichier en objet sans toucher à l'environnement du processus.
Sur un projet récent, le paquet dotenv n'est donc plus indispensable. Il reste présent dans une grande partie des projets existants et des tutoriels, ce qui explique qu'on le croise encore partout.
En Python et dans les autres langages
Python s'appuie le plus souvent sur la bibliothèque python-dotenv et sa fonction load_dotenv(), puis lit les valeurs avec os.environ ou os.getenv(). Un outil en ligne de commande construit par exemple avec Typer et ses annotations de type peut ainsi récupérer une clé d'API dans le .env plutôt que de la demander à chaque lancement. PHP, Ruby, Go ou Rust disposent de bibliothèques équivalentes, et Docker Compose sait lire un .env placé à côté de son fichier de configuration.
Pourquoi le .env ne part jamais sur Git
Un .env rassemble précisément ce qu'un pirate cherche : identifiants de base de données, jetons de paiement, mots de passe de messagerie (par exemple les identifiants SMTP d'une boîte Free consultée via Zimbra utilisée pour envoyer les mails d'un site). Publier ce fichier dans un dépôt public revient à afficher ces secrets à la vue de tous, et les robots qui parcourent les dépôts publics les repèrent très vite.
La protection de base tient en une ligne : ajouter .env au fichier .gitignore du projet avant le premier commit. Si le fichier a déjà été envoyé, le retirer du dépôt ne suffit pas, car il reste dans l'historique : la seule réponse sûre consiste à révoquer et remplacer chaque clé qu'il contenait.
Le rôle du .env.example
Pour que l'équipe sache quelles variables remplir, on versionne à la place un fichier .env.example (parfois .env.sample) : mêmes noms, valeurs factices ou vides. Le nouvel arrivant le copie en .env et y met ses propres valeurs. Ce modèle sert aussi de documentation : une variable absente de l'exemple a toutes les chances d'être oubliée lors d'un déploiement.
Ce que le .env ne protège pas
Le fichier n'est pas chiffré. N'importe qui ayant accès au disque, à une sauvegarde ou à une image Docker qui l'a embarqué peut le lire en clair. Sur un serveur de production, les hébergeurs et les plateformes de déploiement proposent en général leur propre interface pour saisir les variables d'environnement, et les équipes plus importantes passent par un gestionnaire de secrets. Le .env reste avant tout l'outil du poste de développement.
Plusieurs fichiers pour plusieurs environnements
Beaucoup de projets séparent les réglages selon le contexte : .env.development, .env.test, .env.production, parfois un .env.local pour les ajustements personnels jamais partagés. Ces suffixes ne sont pas une règle du langage mais une convention de certains frameworks, qui choisissent le bon fichier selon le mode de lancement. Avec Node.js seul, il suffit d'indiquer le fichier voulu à l'option --env-file.
Créer ou ouvrir un .env sur son ordinateur
Sous Windows, l'Explorateur et le Bloc-notes refusent parfois un nom qui commence par un point ou ajoutent .txt à la fin. Dans le Bloc-notes, choisir « Tous les fichiers » comme type à l'enregistrement et taper .env comme nom évite le piège ; dans un éditeur de code comme VS Code, la création se fait sans difficulté depuis l'arborescence du projet. Sur macOS, le raccourci Cmd + Maj + point affiche les fichiers cachés dans le Finder. Quel que soit le système, un simple éditeur de texte suffit pour l'ouvrir : aucun logiciel spécial n'est nécessaire.
Questions fréquentes
Peut-on mettre des commentaires dans un fichier .env ?
Oui. Une ligne ou une fin de ligne qui commence par # hors guillemets est ignorée. Entre guillemets, le dièse fait partie de la valeur.
Quelle différence entre un .env et les variables d'environnement du système ?
Les variables du système existent pour toute la session ou toute la machine. Le .env est un simple fichier texte propre à un projet, que l'application charge à son démarrage pour créer ses variables.
Faut-il installer dotenv avec Node.js ?
Plus forcément. Node.js sait lire un .env avec l'option --env-file ou la fonction process.loadEnvFile(). Le paquet dotenv reste utile sur les projets qui l'emploient déjà.
Pourquoi ma variable vaut « true » mais mon test échoue ?
Parce que toutes les valeurs lues dans un .env sont des chaînes. "false" est une chaîne non vide, donc considérée comme vraie : il faut comparer explicitement le texte ou le convertir.
Comment partager un .env avec son équipe ?
Jamais par le dépôt Git. On versionne un .env.example sans secrets, et les vraies valeurs passent par un gestionnaire de mots de passe ou de secrets partagé.
