Umgebungsvariablen in Next.js: .env, NEXT_PUBLIC_ | We.Inc
Wie Next.js .env-Dateien lädt, in welcher Reihenfolge, was NEXT_PUBLIC_ beim Build wirklich tut und wie du Werte zur Laufzeit liest. Füge deine .env ein und sieh, was im Browser landet.
Next.js liest .env-Dateien aus dem Projektstamm in process.env. Variablen sind standardmäßig nur auf dem Server verfügbar. Stellst du einem Namen NEXT_PUBLIC_ voran, kopiert Next.js seinen Wert während next build in das Browser-JavaScript, er ist also öffentlich und bis zum nächsten Build eingefroren. Lege niemals ein Geheimnis hinter dieses Präfix.
Ladereihenfolge: Die erste Datei, die eine Variable definiert, gewinnt
Reihenfolge
Quelle
Hinweise
Werte, die Shell oder Host bereits gesetzt haben, gewinnen immer
.env.$(NODE_ENV).local
Zum Beispiel .env.development.local
.env.local
Wird übersprungen, wenn NODE_ENV test ist
.env.$(NODE_ENV)
Zum Beispiel .env.production
.env
Gemeinsame Standardwerte für jede Umgebung
Füge unten den Inhalt einer .env-Datei ein. Der Checker ordnet jede Variable als nur auf dem Server oder an den Browser gesendet ein und markiert öffentliche Namen, die nach Geheimnissen aussehen. Er läuft komplett auf dieser Seite; nichts, was du einfügst, wird hochgeladen.
Füge deine .env-Zeilen in das Feld ein oder bearbeite das Beispiel.
Lies die Tabelle: Jede Variable ist als nur auf dem Server oder an den Browser gesendet markiert.
Reagiere auf jede Warnung, etwa einen NEXT_PUBLIC_-Namen, der KEY, SECRET oder TOKEN enthält.
Baue nach jeder Änderung eines NEXT_PUBLIC_-Werts neu, denn der alte Wert steckt fest im Bundle.
Lege .env-Dateien in den Projektstamm, auch wenn dein Code in einem src-Ordner liegt. Next.js sucht nicht in src danach.
Committe .env und .env.test mit sicheren Standardwerten, wenn dein Team das möchte, aber committe niemals .env*.local-Dateien.
Lies öffentliche Variablen über ihren vollständigen, wörtlichen Namen. process.env[name] oder ein destrukturiertes process.env wird beim Build nicht ersetzt.
Du brauchst ein Docker-Image für Staging und Produktion? Lies Server-Variablen beim dynamischen Rendern und gib alles, was der Browser braucht, als Props weiter.
Nutze loadEnvConfig aus @next/env, um dieselben Dateien in einer ORM-Konfiguration, einem Skript oder einem Test-Setup außerhalb von Next.js zu laden.
Häufige Fragen
Warum ist meine Umgebungsvariable im Browser undefined?
Ohne das Präfix NEXT_PUBLIC_ existiert eine Variable nur auf dem Server, und Next.js ersetzt sie im Client-Code durch einen leeren String. Füge das Präfix nur hinzu, wenn der Wert veröffentlicht werden darf, und baue dann neu.
Ich habe einen NEXT_PUBLIC_-Wert bei meinem Host geändert und nichts ist passiert. Warum?
Öffentliche Werte werden eingesetzt, wenn next build läuft. Ein deploytes Bundle behält den alten Wert, bis du mit dem neuen erneut baust.
Funktioniert .env.local in Tests?
Nein. Wenn NODE_ENV test ist, überspringt Next.js .env.local, damit jeder Testlauf dieselben Werte bekommt. Lege Test-Standardwerte in .env.test und persönliche Overrides in .env.test.local ab.
Kann eine Variable auf eine andere verweisen?
Ja. Schreibe $OTHER_NAME in einen Wert, und Next.js expandiert ihn. Braucht der Wert ein echtes Dollarzeichen, maskiere es als \$.
Auf welchen Wert ist NODE_ENV gesetzt?
Wenn du ihn nicht setzt, verwendet next dev development und andere Befehle verwenden production. Erlaubt sind production, development und test.
Was NEXT_PUBLIC_ wirklich tut
Das Präfix ist eine Anweisung an den Bundler. Während next build wird jedes wörtliche process.env.NEXT_PUBLIC_SOMETHING in deinem Code durch den Wert aus der Umgebung ersetzt, in der der Build lief, und dieser Text landet in den JavaScript-Dateien, die jeder herunterladen kann.
Das hat zwei Folgen. Erstens ist eine öffentliche Variable nie geheim, egal wie die Datei heißt. Zweitens ist sie eingefroren: Wenn du einen Build von Staging in die Produktion übernimmst, nimmt er den Staging-Wert mit.
Werte zur Laufzeit lesen
Server-Code kann jede Variable lesen, öffentlich oder nicht. Damit ein Wert pro Request statt beim Build gelesen wird, rendere die Seite dynamisch, zum Beispiel indem du connection() aus next/server mit await aufrufst, bevor du process.env liest.
Der Browser kann Server-Variablen überhaupt nicht lesen. Braucht eine Client Component einen Laufzeitwert, hole ihn von deinem eigenen Route Handler oder gib ihn als Prop aus einer Server Component weiter.
Schutz vor Lecks
Ein Helfer, der einen API-Schlüssel liest, kann versehentlich in eine Client Component importiert werden. Setze import 'server-only' an den Anfang solcher Dateien, dann schlägt der Build fehl, wenn eine Client-Datei sie einbindet.
Variablen im Code lesen
Reiner Server-Wert in einem Route Handler
DB_URL hat kein Präfix und existiert daher nur auf dem Server. Route Handler und Server Components können sie frei lesen.
Öffentlicher Wert in einer Client Component
Der vollständige, wörtliche Name ist Pflicht. Beim Build tauscht Next.js ihn gegen den Wert aus, sodass der Browser einen einfachen String sieht.
Einen Wert pro Request lesen
Das Warten auf connection() lässt die Seite dynamisch rendern, sodass der Wert vom laufenden Server statt vom Build kommt.
loadEnvConfig wendet dieselbe Ladereihenfolge an und hält Skripte und Test-Setups so im Einklang mit der App.
.env-Checker
Füge .env-Zeilen ein
Wo jede Variable gelesen werden kann
Variable
Verfügbar in
Hinweis
Nur Server
Server und Browser (beim Build eingesetzt)
Keine Variablenzeile
Der Name sieht nach einem Geheimnis aus. Alles mit NEXT_PUBLIC_ ist für jeden Besucher sichtbar.
Verweist auf {v}, das Next.js expandiert.
NODE_ENV akzeptiert nur production, development oder test.
Noch keine Variablen gefunden.
{n} nur auf dem Server, {v} an den Browser gesendet