Umgebungsvariablen & Konfigurationsmanagement für Webanwendungen

Das Festcodieren von Datenbank­zugangsdaten, API-Schlüsseln und Feature-Flags im Quellcode ist einer der häufigsten – und gefährlichsten – Fehler in der Webentwicklung. Umgebungsvariablen trennen die Konfiguration vom Code und ermöglichen es Ihnen, dieselbe Codebasis mit unterschiedlichen Einstellungen für Entwicklung, Staging und Produktion bereitzustellen.

Das 12-Faktor-App-Prinzip

Die Methodik der 12-Faktor-App, entwickelt von den Gründern von Heroku, besagt, dass die Konfiguration in der Umgebung gespeichert werden sollte, niemals im Code­bestand. Das bedeutet:

• Datenbank-URLs, API-Schlüssel und Geheimnisse werden niemals im Versions­kontrollsystem gespeichert
• derselbe Code läuft in jeder Umgebung; nur die Konfiguration ändert sich
• die Konfiguration wird zur Laufzeit über Umgebungsvariablen injiziert

Verwendung von .env-Dateien

# Datenbank
DATABASE_URL=postgres://user:password@localhost:5432/myapp_dev
DATABASE_POOL_SIZE=10

# API-Schlüssel
STRIPE_SECRET_KEY=sk_test_abc123
SENDGRID_API_KEY=SG.xxxxx

# Anwendungs­konfiguration
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000

# Feature-Flags
ENABLE_NEW_CHECKOUT=true
ENABLE_DARK_MODE=false

Lesen von Umgebungsvariablen

// .env Datei im Entwicklungsmodus laden
import 'dotenv/config';

// Variablen abrufen
const dbUrl = process.env.DATABASE_URL;
const port = parseInt(process.env.PORT || '3000', 10);
const isDev = process.env.NODE_ENV === 'development';

// Erforderliche Variablen beim Start validieren
const required = ['DATABASE_URL', 'STRIPE_SECRET_KEY'];
for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Fehlende erforderliche Umgebungsvariable: ${key}`);
  }
}

// Nativ mit PHP
$dbUrl = getenv('DATABASE_URL');
$debug = getenv('APP_DEBUG') === 'true';

// Mit vlucas/phpdotenv (Composer)
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$dotenv->required(['DATABASE_URL', 'APP_KEY'])->notEmpty();

// Zugriff über $_ENV
$apiKey = $_ENV['STRIPE_SECRET_KEY'];

Kritische Regel: .gitignore

# Diese niemals committen
.env
.env.local
.env.production

# Diese committen (Vorlage ohne echte Werte)
# .env.example

Erstellen Sie eine .env.example-Datei mit allen erforderlichen Variablen, aber Platzhalterwerten. Dies dokumentiert, welche Variablen Ihre Anwendung benötigt, ohne Geheimnisse preiszugeben.

DATABASE_URL=postgres://user:password@localhost:5432/myapp
STRIPE_SECRET_KEY=sk_test_your_key_here
NODE_ENV=development
PORT=3000

Umgebungsspezifische Konfiguration

• Entwicklung: Debug-Modus aktiviert, ausführ­liche Protokollierung, lokale Datenbank, Test-API-Schlüssel
• Staging: Debug-Modus deaktiviert, produktionsähnliche Konfiguration, Staging-API-Schlüssel
• Produktion: Debug-Modus deaktiviert, minimale Protokollierung, Produktions­datenbank, echte API-Schlüssel, HTTPS erzwungen

Geheimnisverwaltung in der Produktion

Verlassen Sie sich in der Produktion nicht auf .env-Dateien auf dem Server. Verwenden Sie ordnungs­gemäße Geheimnis­verwaltung:

• Geheimnisse von Cloud-Anbietern: AWS Secrets Manager, Google Secret Manager, Azure Key Vault
• HashiCorp Vault: Selbst gehostete Geheimnis­verwaltung mit Rotation und Audit-Protokollierung
• CI/CD-Geheimnisse: GitHub Actions-Geheimnisse, GitLab CI-Variablen, Vercel-Umgebungsvariablen
• Docker: Docker-Geheimnisse oder Injektion über docker run -e oder docker-compose.yml

Häufige Fehler

• .env in Git committen – auch nur einmal. Wenn Sie dies getan haben, rotieren Sie alle Geheimnisse sofort.
• Dieselbe API-Schlüssel für Entwicklung und Produktion verwenden – verwenden Sie immer Test-/Sandbox-Schlüssel in der Entwicklung.
• Umgebungsvariablen beim Start nicht validieren – mit einer klaren Fehlermeldung schnell scheitern, anstatt später mit einem kryptischen Fehler abzustürzen.
• Auf process.env überall zugreifen – zentralisieren Sie den Konfigurationszugriff in einem einzigen Modul.