.env.local

Kurz: Eine spezielle Variante der .env-Datei für lokale, persönliche Entwicklungsumgebungen — wird per Konvention (z. B. bei Next.js) automatisch NIE eingecheckt, selbst wenn .env selbst versehentlich getrackt würde.

Genauer: Viele Frameworks unterstützen mehrere .env-Dateiebenen mit klarer Priorität (z. B. .env → .env.development → .env.local), wobei spätere Dateien frühere überschreiben. .env.local ist dabei speziell für Werte gedacht, die nur auf dem eigenen Rechner gelten sollen (persönliche API-Test-Keys, lokale Datenbank-URLs) und niemals geteilt werden — im Gegensatz zu .env.example, das als Vorlage ohne echte Geheimnisse ins Repo gehört.

Im Detail

Eine typische Ladereihenfolge (am Beispiel Next.js) sieht so aus, wobei spätere Dateien frühere überschreiben:

.env                  - Basiswerte, gilt in allen Umgebungen (darf eingecheckt werden, wenn ohne Geheimnisse)
.env.development       - nur beim lokalen `npm run dev`
.env.production         - nur beim Produktions-Build
.env.local              - überschreibt ALLES oben, wird NIE eingecheckt (Standard-.gitignore-Eintrag)
.env.development.local  - .env.local speziell für die Entwicklungsumgebung

Der Zweck dieser Stufung: Ein Team kann sinnvolle Standardwerte in .env/.env.development einchecken (z. B. eine lokale Test-Datenbank-URL, die für alle gleich ist), während jede Person individuell abweichende, geheime oder persönliche Werte in .env.local überschreibt — etwa einen eigenen API-Test-Key für einen Drittanbieter-Dienst, ohne dass dieser Key im Repository landet oder mit Kollegen geteilt wird.

Ein häufiger Anfängerfehler: .env.local mit .env.example zu verwechseln. .env.example ist eine bewusst ins Repository eingecheckte Vorlage mit denselben Variablennamen, aber Platzhaltern statt echter Werte (API_KEY=dein_key_hier) — sie dient nur als Dokumentation, welche Variablen ein neues Teammitglied selbst in seiner eigenen .env.local setzen muss.

Warum gerade dieser Name als Konvention gewählt wurde

Die Namenskonvention .local als Suffix ist kein Zufall, sondern folgt einem Muster, das sich über mehrere Frameworks und Tools hinweg wiederfindet (nicht nur bei Environment-Dateien, sondern z. B. auch bei docker-compose.local.yml oder settings.local.py in anderen Ökosystemen): Das Suffix signalisiert eindeutig “diese Datei gehört nur zu MEINER Maschine, nicht zum geteilten Projektzustand” — ein für Entwickler sofort verständliches Signal, welche Datei sicher committet werden darf und welche nicht, ohne jedes Mal in die .gitignore schauen zu müssen.

Zusammenspiel mit CI/CD-Umgebungen

Wichtig ist die Abgrenzung zu Umgebungsvariablen in automatisierten Build-/Deployment-Pipelines (CI/CD): Dort werden Geheimnisse in der Regel NICHT über irgendeine .env-Datei im Dateisystem verwaltet, sondern direkt über die “Secrets”-Verwaltung der jeweiligen Plattform (z. B. GitHub Actions Secrets, Vercel Environment Variables im Projekt-Dashboard) — diese Werte werden erst zur Laufzeit als echte Prozess-Umgebungsvariablen injiziert, tauchen also nie als Datei im Dateisystem des Build-Servers auf. .env.local ist somit ausschließlich ein Werkzeug für die lokale Entwicklungserfahrung auf dem eigenen Rechner, nicht Teil der eigentlichen Deployment-Pipeline.

Typische Stolperfalle: veraltete lokale Werte

Ein praktisches Problem im Team-Alltag: Wird eine neue Umgebungsvariable im Code hinzugefügt (z. B. eine neue API-Integration), aber nicht in .env.example dokumentiert, bemerken andere Teammitglieder das oft erst, wenn ihre lokale Umgebung mit einem kryptischen “undefined”-Fehler abstürzt, weil ihre eigene .env.local die neue Variable noch nicht kennt. Gut geführte Projekte gleichen deshalb .env.example konsequent bei jeder neuen Umgebungsvariable mit ab, oft sogar automatisiert per Skript, das beim Start prüft, ob alle in .env.example gelisteten Variablen auch tatsächlich lokal gesetzt sind.

Siehe auch: .env-Dateien, Environment Variables