Environment Variables

Kurz: Konfigurationswerte (API-Keys, Datenbank-URLs, Secrets), die außerhalb des Codes gesetzt werden — z. B. im Vercel-Dashboard statt fest im Repo.

Genauer: Manche Werte (z. B. Datenbank-Connection-Strings) lassen sich im jeweiligen Dashboard jederzeit erneut einsehen; andere (z. B. API-Keys) werden nur einmal beim Erstellen angezeigt und müssen bei Verlust neu generiert werden. Vercel kennt zusätzlich ein “Sensitive”-Flag: Einmal gesetzt, ist der Wert für niemanden mehr abrufbar — auch nicht per CLI (vercel env pull) oder für den Team-Owner.

Kontext bei uns: Beim Umzug von Bellator zu Emzett mussten fast alle Env-Variablen (Stripe, Resend, Datenbank, Redis) neu erzeugt werden, weil sie an den alten Partner-Accounts hingen.

Im Detail

Lokale Konfiguration

Lokal werden Environment Variables in Next.js üblicherweise über eine .env.local-Datei gesetzt (per Konvention nie eingecheckt, in .gitignore ausgeschlossen — sonst landen Secrets im Git-Verlauf, wo sie auch nach nachträglichem Löschen der Datei weiter auffindbar bleiben, da Git-History standardmäßig nichts vergisst). Next.js liest dabei automatisch mehrere .env*-Dateien in einer festen Prioritätsreihenfolge (.env.local überschreibt .env.development/.env.production, die wiederum .env überschreiben) — praktisch, um z. B. lokale Entwicklungswerte von echten Produktionswerten sauber zu trennen, ohne beide in derselben Datei zu vermischen.

Das NEXT_PUBLIC_-Präfix

Ein wichtiger Next.js-spezifischer Unterschied: Variablen mit dem Präfix NEXT_PUBLIC_ werden beim Build ins Client-Bundle eingebettet und sind damit für jeden im Browser einsehbar (z. B. über die Entwicklertools) — alle anderen Variablen bleiben ausschließlich serverseitig verfügbar. Ein Geheimnis versehentlich mit NEXT_PUBLIC_-Präfix zu versehen, macht es effektiv öffentlich. Technisch passiert das, weil Next.js beim Build alle process.env.NEXT_PUBLIC_*-Referenzen im Code direkt durch den tatsächlichen Wert ersetzt (String-Substitution zur Build-Zeit) — es handelt sich NICHT um eine Laufzeit-Abfrage, weshalb eine Änderung dieser Werte immer einen neuen Build erfordert, damit sie wirksam wird.

# .env.local (nie committen)
DATABASE_URL=postgresql://...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...  # bewusst öffentlich, für Client-seitiges Stripe.js
STRIPE_SECRET_KEY=sk_live_...                    # bleibt serverseitig

Umgebungstrennung bei Vercel

Bei Vercel werden Werte zusätzlich pro Umgebung (Production/Preview/Development) getrennt verwaltet — ein Preview-Deploy kann z. B. mit einer Test-Datenbank statt der echten Produktionsdatenbank arbeiten, ohne dass im Code irgendetwas unterschieden werden muss. Das ist besonders wertvoll bei destruktiven Testszenarien: Ein Preview-Deploy, der versehentlich Testdaten löscht oder verändert, trifft dadurch niemals die echte Produktionsdatenbank, solange die Umgebungstrennung konsequent eingehalten wird.

Das “Sensitive”-Flag

Vercel kennt zusätzlich ein “Sensitive”-Flag: Einmal gesetzt, ist der Wert für niemanden mehr abrufbar — auch nicht per CLI (vercel env pull) oder für den Team-Owner. Das ist eine bewusste Einbahnstraße: Der Wert kann weiterhin von der Anwendung zur Laufzeit genutzt werden, aber niemand kann ihn nachträglich im Klartext wieder auslesen, selbst mit vollen Administrationsrechten für das Projekt. Praktisch bedeutet das: Vor dem Setzen eines sensiblen Werts als “Sensitive” sollte er sicher an anderer Stelle (z. B. einem Passwort-Manager) hinterlegt werden — ein verlorener sensibler Wert lässt sich nur durch komplettes Neu-Generieren beim ursprünglichen Anbieter wiederherstellen, nicht durch erneutes Auslesen aus Vercel.

Siehe auch: Vercel, Bearer Token