Votre application a besoin d’une URL de base de données. Sur votre ordinateur portable, il s’agit d’une base de données locale, en CI une base de données jetable et en production un cluster géré. Coder en dur l’un d’entre eux signifie changer le code pour chaque environnement. Les variables d’environnement résolvent ce problème. Le code se lit DATABASE_URL et chaque environnement fournit sa propre valeur.

Cette idée est au cœur de la méthode Twelve-Factor App, qui stipule que la configuration qui varie entre les déploiements appartient à l’environnement. Nous avons testé le comportement ci-dessous avec Python 3.13 sous Windows. Chaque sortie affichée provient de cette exécution.

Que sont les variables d’environnement ?

Chaque processus en cours d’exécution possède un ensemble de valeurs de texte nommées appelé son environnement. Des exemples familiers sont PATH, qui indique au shell où trouver les programmes, et HOME ou USERPROFILE. Votre propre application peut utiliser le même mécanisme pour des paramètres tels que APP_PORT, LOG_LEVEL ou DATABASE_URL.

Définition des variables d’environnement

Celles-ci ne durent que pour la session de terminal en cours. Pour les rendre permanents, ajoutez-les à un profil shell tel que ~/.bashrc ou, sous Windows, utilisez les paramètres d’environnement système ou setx. Pour les applications, il est généralement préférable de les fournir au moment du déploiement plutôt que de les définir à l’échelle du système.

Les lire en code

import os

port = os.environ.get("APP_PORT", "8000")   # default if missing
print(port)                                  # 8000

db = os.environ["DATABASE_URL_MISSING_DEMO"]
# KeyError: 'DATABASE_URL_MISSING_DEMO'

Utilisez .get() avec une valeur par défaut pour les paramètres facultatifs. Utilisez des crochets, qui élèvent KeyError, pour les paramètres sans lesquels l’application ne peut pas fonctionner. D’autres langages sont similaires : process.env.APP_PORT dans Node.js, System.getenv("APP_PORT") en Java et os.Getenv("APP_PORT") dans Go.

Tout est une chaîne

Cela attire les gens dans toutes les langues. Nous avons défini un port puis y avons ajouté « 1 » :

os.environ["APP_PORT"] = "8080"
port = os.environ["APP_PORT"]
print(type(port).__name__, repr(port), port + "1")
# str '8080' 80801

os.environ["APP_PORT"] = 8080
# TypeError: str expected, not int

La valeur est revenue sous forme de texte et l’ajout a produit 80801, et non 8081. Convertissez explicitement, comme dans int(os.environ["APP_PORT"]). Les booléens sont pires :

os.environ["DEBUG"] = "false"
print(bool(os.environ["DEBUG"]))   # True

Toute chaîne non vide est véridique en Python, donc "false" est devenu True. Le mode débogage aurait été activé en production. Analyser délibérément les booléens :

def env_bool(name, default=False):
    value = os.environ.get(name)
    if value is None:
        return default
    return value.strip().lower() in {"1", "true", "yes", "on"}

env_bool("DEBUG")                   # False
env_bool("NOT_SET", default=True)   # True

Comment les processus en héritent

Un processus enfant reçoit une copie de l’environnement de son parent. Nous avons démarré les processus Python enfants pour voir ceci :

child sees: 8080 inherited     # default: full copy of the parent's environment
child sees: 9000 None          # given a custom env: only what we passed
parent sees child var: None    # a child's changes never flow back

Trois leçons pratiques suivent. Les variables que vous exportez sont visibles par chaque programme que vous lancez, y compris les scripts que vous n’avez pas écrits, ce qui est important pour les secrets. Passer un environnement personnalisé remplace le tout, alors incluez tout ce dont l’enfant a besoin. Et un script ne peut pas modifier les variables de son shell parent, c’est pourquoi les outils vous demandent de source un fichier au lieu de l’exécuter.

Fichiers .env

Taper de nombreuses variables à la main devient fastidieux, donc la plupart des projets conservent les valeurs de développement local dans un fichier .env :

# local development only
APP_PORT=8080
DATABASE_URL="postgres://dev:devonly@localhost:5432/shop"
FEATURE_SEARCH=true

Les bibliothèques telles que python-dotenv et dotenv pour Node.js chargent ce fichier au démarrage. Node.js 20.6 et versions ultérieures peuvent également en charger un de manière native avec --env-file. Pour voir l’idée, nous avons écrit un petit analyseur, qui a transformé le fichier ci-dessus en :

{'APP_PORT': '8080',
 'DATABASE_URL': 'postgres://dev:devonly@localhost:5432/shop',
 'FEATURE_SEARCH': 'true'}

Utilisez une vraie bibliothèque en pratique. Il gère les guillemets, les échappements, les commentaires et les valeurs multilignes que notre version 10 lignes ignore. Par défaut, la plupart des chargeurs dotenv ne remplacent pas les variables déjà définies, de sorte que les valeurs d’environnement réelles l’emportent sur le fichier. C’est généralement ce que vous voulez.

Valider la configuration au démarrage

Une variable manquante devrait arrêter l’application immédiatement avec un message clair, sans provoquer d’erreur déroutante une heure plus tard. Nous avons vérifié les paramètres requis lors du chargement :

REQUIRED = ["DATABASE_URL", "SECRET_KEY"]

def check_required(env):
    missing = [k for k in REQUIRED if not env.get(k)]
    if missing:
        raise SystemExit(f"Missing required settings: {', '.join(missing)}")

# Missing required settings: SECRET_KEY

Les bibliothèques de configuration typées vont plus loin. Les paramètres Pydantic en Python, zod ou envalid dans Node.js et les propriétés de configuration de Spring en Java convertissent tous les types et signalent chaque problème à la fois.

Variables d’environnement et secrets

Les variables d’environnement sont le moyen courant de transmettre des secrets tels que des clés API à une application, et elles sont bien meilleures que de les coder en dur. Ils ont des faiblesses à connaître :

• Les processus enfants en héritent, comme notre test l’a montré.
• Ils peuvent apparaître dans les rapports d’erreur, les pages de débogage et les journaux qui vident l’environnement.
• Sur certains systèmes, d’autres processus exécutés par le même utilisateur peuvent les lire.

Pour la production, de nombreuses équipes conservent les secrets dans un gestionnaire dédié, tel que HashiCorp Vault, AWS Secrets Manager, Azure Key Vault ou Google Secret Manager, et les injectent au moment de l’exécution. Certains préfèrent monter les secrets sous forme de fichiers plutôt que de variables. Quoi qu’il en soit, n’imprimez jamais la configuration dans les journaux et alternez tout secret jamais validé dans Git, même après l’avoir supprimé de l’historique.

Dans Docker et CI

# Docker (not run for this article)
docker run -e APP_PORT=8080 --env-file .env.production myapp

# GitHub Actions (not run for this article)
env:
  APP_PORT: 8080
  API_KEY: ${{ secrets.API_KEY }}

Les plateformes CI stockent les secrets cryptés et les masquent dans les journaux. Évitez d’intégrer des secrets dans les images Docker avec ENV dans le Dockerfile, car ils restent lisibles dans les calques d’image. Consultez notre didacticiel Docker Compose et guide GitHub Actions CI/CD pour les configurations complètes.

Meilleures pratiques

• Utilisez des noms clairs en majuscules avec un préfixe, tel que SHOP_DB_URL.
• Lisez toute la configuration dans un module, convertissez-y les types et validez au démarrage.
• Fournissez des valeurs par défaut sûres uniquement pour les paramètres non sensibles.
• Gardez .env hors de Git et maintenez un .env.example.
• Utilisez un gestionnaire de secrets en production pour les valeurs sensibles.
• Documentez chaque variable, son type et un exemple de valeur.

Problèmes de variables d’environnement de débogage

Lorsqu’une application se comporte comme si un paramètre manquait, effectuez ces vérifications dans l’ordre :

1. Est-elle placée au bon endroit ? Une variable exportée dans un onglet du terminal n’existe pas dans un autre, ou dans un service démarré par le système.
2. L’application a-t-elle été redémarrée ? Un processus en cours d’exécution conserve l’environnement avec lequel il a démarré. La modification ultérieure d’une variable n’a aucun effet jusqu’au redémarrage.
3. Le nom est-il exact ? Les noms sont sensibles à la casse sous Linux et macOS, donc App_Port et APP_PORT sont des variables différentes. Windows les traite de la même manière.
4. Un fichier .env le remplace-t-il ou est-il ignoré ? Vérifiez si votre chargeur remplace les valeurs existantes et quel fichier il lit réellement.
5. Y a-t-il des guillemets ou des espaces parasites ? Une valeur copiée avec un espace de fin ou des guillemets supplémentaires peut ne pas être analysée ou ne pas correspondre, d’une manière difficile à repérer.

Pour voir ce qu’un processus a réellement reçu, affichez les noms des variables, jamais les valeurs des secrets. Sous Linux et macOS, printenv répertorie l’environnement du shell actuel, et dans PowerShell Get-ChildItem Env: fait de même. À l’intérieur d’un conteneur, l’exécution de env à docker exec affiche la vue du conteneur, qui est souvent différente de celle de votre propre shell.

Un dernier conseil : enregistrez une ligne au démarrage qui répertorie les paramètres facultatifs qui utilisent leurs valeurs par défaut. Cela ne coûte rien et répond surtout à « pourquoi fait-il cela ? » des questions tout de suite.

Pour conclure

Les variables d’environnement sont simples, mais elles cachent quelques pièges : tout est une chaîne, les enfants en héritent et des secrets peuvent s’y échapper. Traitez-les comme une entrée dans votre application. Lisez-les en un seul endroit, convertissez-les et validez-les rapidement, et gardez les vrais secrets des fichiers qui sont validés.

Questions fréquentes

Continuez à apprendre