Ihre App benötigt eine Datenbank-URL. Auf Ihrem Laptop ist es eine lokale Datenbank, in CI eine Wegwerfdatenbank und in der Produktion ein verwalteter Cluster. Die harte Codierung einer davon bedeutet, dass der Code für jede Umgebung geändert werden muss. Umgebungsvariablen lösen dieses Problem. Der Code lautet DATABASE_URL und jede Umgebung liefert ihren eigenen Wert.

Diese Idee ist von zentraler Bedeutung für die Zwölf-Faktor-App-Methode, die besagt, dass Konfigurationen, die zwischen Bereitstellungen variieren, in die Umgebung gehören. Wir haben das folgende Verhalten mit Python 3.13 unter Windows getestet. Alle angezeigten Ausgaben stammen aus diesem Lauf.

Was sind Umgebungsvariablen?

Jeder laufende Prozess verfügt über eine Reihe benannter Textwerte, die als Umgebung bezeichnet werden. Bekannte Beispiele sind PATH, das der Shell mitteilt, wo Programme zu finden sind, und HOME oder USERPROFILE. Ihre eigene App kann denselben Mechanismus für Einstellungen wie APP_PORT, LOG_LEVEL oder DATABASE_URL verwenden.

Umgebungsvariablen festlegen

Diese gelten nur für die aktuelle Terminalsitzung. Um sie dauerhaft zu machen, fügen Sie sie einem Shell-Profil wie ~/.bashrc hinzu oder verwenden Sie unter Windows die Systemumgebungseinstellungen oder setx. Bei Anwendungen ist es in der Regel besser, sie zum Zeitpunkt der Bereitstellung bereitzustellen, als sie systemweit festzulegen.

Lesen Sie sie im 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'

Verwenden Sie .get() mit einer Standardeinstellung für optionale Einstellungen. Verwenden Sie eckige Klammern, die KeyError erhöhen, für Einstellungen, ohne die die App nicht funktionieren kann. Andere Sprachen sind ähnlich: process.env.APP_PORT in Node.js, System.getenv("APP_PORT") in Java und os.Getenv("APP_PORT") in Go.

Alles ist eine Zeichenfolge

Das fängt Menschen in jeder Sprache ein. Wir haben einen Port festgelegt und dann „1“ hinzugefügt:

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

Der Wert kam als Text zurück und das Hinzufügen ergab 80801, nicht 8081. Konvertieren Sie explizit, wie in int(os.environ["APP_PORT"]). Boolesche Werte sind schlimmer:

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

Jede nicht leere Zeichenfolge ist in Python wahr, daher wurde "false" zu True. In der Produktion wäre der Debug-Modus eingeschaltet gewesen. Boolesche Werte bewusst analysieren:

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

Wie Prozesse sie erben

Ein untergeordneter Prozess erhält eine Kopie der Umgebung seines übergeordneten Prozesses. Wir haben untergeordnete Python-Prozesse gestartet, um Folgendes zu sehen:

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

Es folgen drei praktische Lektionen. Von Ihnen exportierte Variablen sind für jedes Programm, das Sie starten, sichtbar, einschließlich Skripten, die Sie nicht geschrieben haben, was für Geheimnisse wichtig ist. Die Übergabe einer benutzerdefinierten Umgebung ersetzt das Ganze, also schließen Sie alles ein, was das Kind braucht. Und ein Skript kann die Variablen seiner übergeordneten Shell nicht ändern, weshalb Tools Sie auffordern, eine Datei zu source, anstatt sie auszuführen.

.env-Dateien

Das manuelle Eingeben vieler Variablen wird mühsam, daher behalten die meisten Projekte lokale Entwicklungswerte in einer .env-Datei:

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

Bibliotheken wie python-dotenv und dotenv für Node.js laden diese Datei beim Start. Node.js 20.6 und höher können eines auch nativ mit --env-file laden. Um die Idee zu veranschaulichen, haben wir einen kleinen Parser geschrieben, der die obige Datei in Folgendes umwandelte:

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

Nutzen Sie in der Praxis eine echte Bibliothek. Es verarbeitet Anführungszeichen, Escapezeichen, Kommentare und mehrzeilige Werte, die unsere 10-zeilige Version ignoriert. Standardmäßig überschreiben die meisten Dotenv-Loader Variablen, die bereits festgelegt sind, nicht, sodass echte Umgebungswerte die Datei überwiegen. Das ist normalerweise das, was Sie wollen.

Validieren Sie die Konfiguration beim Start

Eine fehlende Variable sollte die App sofort mit einer klaren Meldung stoppen und nicht eine Stunde später einen verwirrenden Fehler verursachen. Wir haben beim Laden überprüft, ob die erforderlichen Einstellungen erforderlich sind:

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

Typisierte Konfigurationsbibliotheken gehen noch weiter. Pydantic-Einstellungen in Python, zod oder envalid in Node.js und die Konfigurationseigenschaften von Spring in Java konvertieren alle Typen und melden jedes Problem auf einmal.

Umgebungsvariablen und Geheimnisse

Umgebungsvariablen sind die gängige Methode, Geheimnisse wie API-Schlüssel an eine App zu übergeben, und sie sind weitaus besser, als sie hart zu codieren. Sie haben Schwächen, über die Sie Bescheid wissen sollten:

• Kindprozesse erben sie, wie unser Test gezeigt hat.
• Sie können in Absturzberichten, Debug-Seiten und Protokollen erscheinen, die die Umgebung sichern.
• Auf einigen Systemen können andere Prozesse, die vom selben Benutzer ausgeführt werden, sie lesen.

Für die Produktion bewahren viele Teams Geheimnisse in einem dedizierten Manager wie HashiCorp Vault, AWS Secrets Manager, Azure Key Vault oder Google Secret Manager auf und injizieren sie zur Laufzeit. Manche bevorzugen das Mounten von Geheimnissen als Dateien statt als Variablen. Drucken Sie auf keinen Fall die Konfiguration in Protokollen aus und rotieren Sie alle Geheimnisse, die jemals an Git übergeben wurden, auch nachdem Sie sie aus dem Verlauf entfernt haben.

In Docker und 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 }}

CI-Plattformen speichern Geheimnisse verschlüsselt und maskieren sie in Protokollen. Vermeiden Sie es, Geheimnisse mit ENV in der Docker-Datei in Docker-Images zu backen, da diese in den Image-Ebenen lesbar bleiben. Vollständige Setups finden Sie in unserem Docker Compose-Tutorial und in unserem GitHub Actions CI/CD-Leitfaden.

Best Practices

• Verwenden Sie klare Namen in Großbuchstaben mit einem Präfix, z. B. SHOP_DB_URL.
• Lesen Sie die gesamte Konfiguration in einem Modul, konvertieren Sie dort Typen und validieren Sie sie beim Start.
• Stellen Sie sichere Standardeinstellungen nur für nicht sensible Einstellungen bereit.
• Halten Sie .env aus Git fern und behalten Sie eine .env.example bei.
• Setzen Sie in der Produktion für sensible Werte einen Secrets-Manager ein.
• Dokumentieren Sie jede Variable, ihren Typ und einen Beispielwert.

Debuggen von Umgebungsvariablenproblemen

Wenn sich eine App so verhält, als ob eine Einstellung fehlt, führen Sie diese Prüfungen der Reihe nach durch:

1. Ist sie an der richtigen Stelle eingestellt? Eine in einer Terminalregisterkarte exportierte Variable existiert in einer anderen oder in einem vom System gestarteten Dienst nicht.
2. Wurde die App neu gestartet? Ein laufender Prozess behält die Umgebung bei, mit der er gestartet wurde. Eine spätere Änderung einer Variablen hat bis zum Neustart keine Auswirkung.
3. Ist der Name genau? Bei Namen wird unter Linux und macOS die Groß-/Kleinschreibung beachtet, daher sind App_Port und APP_PORT unterschiedliche Variablen. Windows behandelt sie als gleich.
4. Überschreibt eine .env-Datei diese oder wird sie ignoriert? Überprüfen Sie, ob Ihr Loader vorhandene Werte überschreibt und welche Datei er tatsächlich liest.
5. Gibt es vereinzelte Anführungszeichen oder Leerzeichen? Ein mit einem nachgestellten Leerzeichen oder zusätzlichen Anführungszeichen kopierter Wert kann auf schwer erkennbare Weise nicht analysiert werden oder nicht übereinstimmen.

Um zu sehen, was ein Prozess wirklich empfangen hat, geben Sie die Variablennamen aus, niemals die Werte von Geheimnissen. Unter Linux und macOS listet printenv die aktuelle Shell-Umgebung auf, und in PowerShell Get-ChildItem Env: macht es dasselbe. Wenn Sie innerhalb eines Containers env bis docker exec ausführen, wird die Ansicht des Containers angezeigt, die sich oft von der Ihrer eigenen Shell unterscheidet.

Ein letzter Tipp: Protokollieren Sie beim Start eine Zeile, in der aufgeführt ist, welche optionalen Einstellungen ihre Standardeinstellungen verwenden. Es kostet nichts und antwortet am meisten: „Warum macht es das?“ Fragen sofort.

Fazit

Umgebungsvariablen sind einfach, aber sie bergen ein paar Fallstricke: Alles ist ein String, Kinder erben sie und durch sie können Geheimnisse durchsickern. Behandeln Sie sie als Eingabe für Ihre App. Lesen Sie sie an einem Ort, konvertieren und validieren Sie sie frühzeitig und halten Sie echte Geheimnisse aus Dateien fern, die festgeschrieben werden.

Häufige Fragen

Lerne weiter