Was bewirkt der Präfix NEXT_PUBLIC_?

Der Wert wird beim Bauen ins Browser-JavaScript eingesetzt und ist damit öffentlich. — Genau umgekehrt zur Intuition mancher: Der Präfix macht öffentlich, er schützt nicht. Ohne ihn bleibt der Wert auf dem Server.

Du liest process.env.STRIPE_SECRET_KEY in einer Client-Komponente. Was passiert?

Er ist undefined – ohne Präfix kommt er nicht im Browser an. — Das ist die eingebaute Absicherung. Wer den Wert braucht, holt ihn in einer Server-Komponente oder Server Action – dort ist er vorhanden.

Was verlierst du mit output: "export"?

Server Actions · Revalidierung und ISR · Middleware — Statische Seiten sind gerade das Einzige, was übrig bleibt. Alles Serverseitige entfällt – deshalb passt der Export nur zu reinen Inhaltsseiten.

Warum kannst du NEXT_PUBLIC_-Werte nicht im selben Abbild zwischen Test und Produktion umstellen?

Sie werden beim Bauen fest eingesetzt, nicht beim Starten gelesen. — Der Wert steckt danach im ausgelieferten JavaScript. Wer dasselbe Abbild in mehreren Umgebungen benutzen will, muss diese Werte zur Laufzeit vom Server holen.

← Zur Übersicht

Kern 10 Min Lesezeit

Umgebung & Deployment

Geheimnisse, die geheim bleiben – und der Weg nach draußen

Baut auf: Server- und Client-Komponenten

In einem Satz

Nur Variablen mit NEXT_PUBLIC_ landen im Browser. Alles andere bleibt auf dem Server – und dort gehört es auch hin.

Umgebungsvariablen

.env.local

DATABASE_URL="postgres://…"          # bleibt auf dem Server
STRIPE_SECRET_KEY="sk_live_…"        # bleibt auf dem Server

NEXT_PUBLIC_SITE_URL="https://beispiel.de"   # landet im Browser
NEXT_PUBLIC_PLAUSIBLE_ID="beispiel.de"       # landet im Browser

Die Regel für UmgebungsvariablenWerte aus `.env`. Nur was mit `NEXT_PUBLIC_` beginnt, landet im Browser – alles andere bleibt auf dem Server.→ ist einfach: Der Präfix NEXT_PUBLIC_ macht einen Wert öffentlich. Alles ohne diesen Präfix ist in Client-Komponenten schlicht undefined.

Stolperstein NEXT_PUBLIC_ ist keine Formalität

Der Wert wird beim Bauen fest in das JavaScript eingesetzt, das jeder herunterladen kann. Ein Schlüssel mit diesem Präfix ist damit veröffentlicht – auch wenn er nur in einer scheinbar unscheinbaren Datei steht.

dateien.txt

.env                 für alle, im Repository (nur harmlose Werte!)
.env.local           deine lokalen Geheimnisse – gehört in .gitignore
.env.production      beim Produktionsbau

Auf dem Server (Vercel, Docker, …) setzt du sie in der Oberfläche
bzw. als Umgebungsvariablen – nicht als Datei im Image.

Tipp Versehentliche Importe verhindern

Das Paket server-onlyEin kleines Paket, das den Build abbricht, falls eine Datei versehentlich im Browser landet. Schutz für Code mit Geheimnissen.→ bricht den Build ab, sobald eine Datei mit Geheimnissen doch einmal von einer Client-Komponente importiert wird. Ein import "server-only"; oben in der Datei – und ein ganzer Fehlertyp ist ausgeschlossen.

Was beim Bauen entsteht

build.txt

npm run build

  .next/            das Ergebnis
    static/         Dateien mit Hash im Namen, ewig cachebar
    server/         der serverseitige Teil

npm run start       startet den Node-Server auf Port 3000

Wichtig: Umgebungsvariablen mit NEXT_PUBLIC_ werden beim Bauen eingesetzt, nicht beim Starten. Wer dasselbe Abbild in Test und Produktion benutzt, kann sie also nicht mehr ändern – dafür braucht es einen eigenen Build je Umgebung.

Wohin damit

optionen.txt

Vercel        vom selben Team wie Next.js, alles ohne Konfiguration
              Server Actions, ISR, Bildoptimierung funktionieren sofort

Eigener Node  npm run build && npm run start hinter einem Reverse Proxy
              volle Kontrolle, du kümmerst dich um Skalierung und Cache

Docker        output: "standalone" in next.config.js erzeugt ein
              schlankes Abbild mit nur den nötigen Abhängigkeiten

Statisch      output: "export" – nur wenn du KEINE Server-Funktionen
              nutzt. Kein ISR, keine Server Actions, keine Middleware.

Achtung output: export ist eine Einbahnstraße

Der rein statische Export klingt verlockend, schaltet aber alles ab, wofür man Next.js nimmt: Server Actions, Revalidierung, Bildoptimierung, Middleware. Für eine reine Dokumentationsseite in Ordnung – sonst selten die richtige Wahl.

Vor dem ersten Deploy

Nimm es, wenn …

+
npm run build lokal laufen lassen und die Symbolspalte prüfen
+
Alle Geheimnisse in der Zielumgebung eintragen – nicht ins Repository
+
Eine Fehlerseite und eine 404 gestalten
+
robots.ts und sitemap.ts ergänzen

Lass es, wenn …

−
Nur im Entwicklungsmodus getestet haben
−
NEXT_PUBLIC_ für etwas, das geheim bleiben soll
−
.env.local versehentlich einchecken

▸ Genauer erklärt: Node oder Edge optional

Serverseitiger Code läuft standardmäßig in Node. Für einzelne Routen kannst du auf die Edge RuntimeEine schlanke Ausführungsumgebung nah am Nutzer. Schnell zu starten, kann aber weniger als Node.→ umstellen – schneller im Start, näher am Nutzer, aber mit weniger Möglichkeiten.

runtime.ts

export const runtime = "edge";     // in einer page.tsx oder route.ts

// Edge kann:      fetch, Web-Crypto, Streams
// Edge kann nicht: fs, net, die meisten Datenbanktreiber

Gut zu wissen Im Zweifel Node

Edge lohnt sich für kleine, häufig aufgerufene Endpunkte ohne Datenbank – Weiterleitungen, Feature-Schalter, einfache Prüfungen. Alles mit Datenbank bleibt in Node. Middleware läuft ohnehin immer in der Edge-Umgebung.

Sitzt das schon?

4 Fragen zu dieser Lektion. Falsche Antworten landen in deiner Statistik.

Umgebungsvariablen

Was beim Bauen entsteht

Wohin damit

Vor dem ersten Deploy

Sitzt das schon?

Ihr braucht React-Verstärkung im Team?