.env-Variablen in Next.js: Build-Time vs. Runtime

Kennst du das Problem? Du hast eine neue Funktionalität in deiner Next.js-Anwendung implementiert und dabei ein paar neue Umgebungsvariablen in einer .env-Datei definiert. Nach dem Start der Anwendung funktioniert jedoch nichts, und du fragst dich, warum die Variablen nicht geladen werden. Oder vielleicht greifst du zur Laufzeit auf process.env zu und erhältst undefined, obwohl die Variable korrekt gesetzt scheint.

Solche Situationen sind nicht ungewöhnlich, denn das Laden und die Verwendung von .env-Variablen hängen stark davon ab, wann und wie diese im Build-Prozess oder zur Laufzeit verarbeitet werden. Besonders in komplexeren Projekten kann das schnell zu Verwirrung führen.

In diesem Artikel erfährst du:

• wie .env-Dateien funktionieren und wann ihre Variablen im Build- oder Laufzeitprozess gelesen werden,
• typische Fehlerquellen und Best Practices,
• wie du Umgebungsvariablen sicher validieren kannst,

Am Ende wirst du verstehen, wie .env-Variablen in Next.js verarbeitet werden und wie du sicherstellst, dass sie korrekt funktionieren – von der Entwicklung bis hin zur Produktion.

2. Grundlagen von .env-Dateien

Was sind .env-Dateien?

.env-Dateien sind einfache Textdateien, die Konfigurationswerte in Form von Schlüssel-Wert-Paaren speichern. Diese Werte werden in der Regel als Umgebungsvariablen genutzt, um sensible oder konfigurierbare Daten von deinem Quellcode zu trennen. Typische Beispiele sind Datenbankverbindungen, API-Schlüssel oder Tokens:

DB_HOST=localhost
DB_USER=myuser
DB_PASS=secretpassword
API_KEY=123456789

Die Variablen werden in den Anwendungskontext geladen und sind über process.env zugänglich.

Warum werden .env-Dateien verwendet?

.env-Dateien haben sich aus mehreren Gründen als Best Practice etabliert:

• Sicherheit: Keine sensiblen Daten wie API-Schlüssel oder Passwörter im Quellcode.
• Flexibilität: Unterschiedliche Konfigurationen für verschiedene Umgebungen (z. B. Entwicklung, Test, Produktion).
• Portabilität: Einfache Weitergabe von Konfigurationen an andere Entwickler oder CI/CD-Pipelines.

Unterschiede zwischen den verschiedenen .env-Dateien

Next.js unterstützt mehrere .env-Dateien, die in spezifischen Szenarien zum Einsatz kommen. Hier ein Überblick:

Wie werden .env-Dateien geladen?

Next.js nutzt @next/env, um die Werte aus den .env-Dateien zu lesen und in process.env zu laden. Wichtig: Diese Variablen sind standardmäßig nur im Node.js-Kontext (also auf dem Server) verfügbar. Um Variablen im Browser (Client) zugänglich zu machen, müssen sie mit NEXT_PUBLIC_ präfixiert werden:

# Nur auf dem Server verfügbar
DB_HOST=localhost

# Sowohl im Server als auch im Client verfügbar
NEXT_PUBLIC_API_URL=https://api.example.com

Gut zu wissen: Variablen ohne Präfix NEXT_PUBLIC_ sind im Browser nicht verfügbar, um sensible Daten zu schützen.

3. Reihenfolge und Priorität im Leseprozess

Next.js verarbeitet .env-Dateien in einer festgelegten Reihenfolge, wobei die spezifischeren Dateien immer Vorrang vor den allgemeineren haben. Dies ermöglicht es, Konfigurationen flexibel anzupassen, z. B. für lokale Entwicklungen oder spezifische Umgebungen wie Produktion und Test.

Reihenfolge der Datei-Ladung

Wenn Next.js Umgebungsvariablen lädt, durchläuft es die folgenden Dateien in der angegebenen Reihenfolge. Sobald eine Variable definiert ist, wird sie nicht von Dateien mit geringerer Priorität überschrieben:

1. .env.$(NODE_ENV).local
   → Z. B. .env.development.local oder .env.production.local. Diese Datei hat die höchste Priorität und ist ideal für lokale Anpassungen. Sie sollte niemals versioniert werden und eignet sich für Variablen, die nur auf deinem Rechner existieren sollen.
2. .env.local
   → Gilt für alle Umgebungen und hat ebenfalls eine hohe Priorität. Auch diese Datei sollte niemals in Git versioniert werden.
3. .env.$(NODE_ENV)
   → Z. B. .env.development oder .env.production. Diese Datei ist spezifisch für die aktuelle Umgebung und wird üblicherweise auch nicht versioniert, da sie sensible Daten enthalten kann.
4. .env
   → Die allgemeine Basisdatei mit den Standardwerten, die für alle Umgebungen gelten. Auch diese Datei sollte nicht versioniert werden, um sensible Daten zu schützen.

Beispiel: Wie Priorität funktioniert

Angenommen, du hast die folgenden Dateien in deinem Projekt:

# .env
DB_HOST=base.example.com
API_KEY=default-key

# .env.development
DB_HOST=dev.example.com

# .env.local
API_KEY=local-key

# .env.development.local
DB_HOST=local-dev.example.com

Wenn du die Anwendung in der Entwicklungsumgebung (NODE_ENV=development) startest, sieht das Ergebnis von process.env wie folgt aus:

Gut zu wissen: Die allgemeineren Werte aus .env und .env.development werden durch die spezifischeren Dateien .env.local und .env.development.local überschrieben.

Warum ist die Reihenfolge wichtig?

Die festgelegte Reihenfolge ermöglicht es dir, unterschiedliche Konfigurationswerte zu kombinieren:

• Globale Standardwerte in .env (nur lokal).
• Umgebungsspezifische Werte in .env.development oder .env.production.
• Lokale Overrides, die deine persönlichen oder projektspezifischen Anpassungen enthalten, in .env.local.

Tabellenübersicht der Prioritäten

Wichtig: .env-Dateien sollten niemals versioniert werden, da sie oft sensible Daten wie Passwörter oder API-Schlüssel enthalten. Nutze stattdessen .gitignore, um diese Dateien vom Repository auszuschließen.

Mit diesem Wissen kannst du .env-Dateien effizient nutzen und sicherstellen, dass die richtigen Werte in der richtigen Umgebung geladen werden. Im nächsten Abschnitt werfen wir einen Blick auf die Unterschiede zwischen Build-Time und Runtime und warum diese Unterscheidung für Umgebungsvariablen entscheidend ist.

4. Build- und Laufzeitunterschiede

Ein häufiger Stolperstein bei .env-Variablen in Next.js ist die Unterscheidung zwischen Build-Time und Runtime. Variablen können in beiden Phasen genutzt werden, je nach Kontext und Verwendungszweck. Dabei ist zu beachten, ob die Variable auch auf dem Client benötigt wird (mit NEXT_PUBLIC_) oder ausschließlich auf dem Server verwendet wird.

Was passiert zur Build-Time?

Während der Build-Time werden .env-Variablen geladen und in den Build-Prozess von Next.js eingebunden. Dies betrifft sowohl:

1. Client-seitige Variablen (mit NEXT_PUBLIC_), die in den JavaScript-Code für den Browser eingebettet werden, als auch
2. Server-seitige Variablen (ohne NEXT_PUBLIC_), die ausschließlich im Node.js-Kontext benötigt werden.

Beispiel 1: Client-seitige Variablen (NEXT_PUBLIC_)

Client-seitige Variablen müssen mit NEXT_PUBLIC_ präfixiert sein. Sie werden während des Builds in den Client-Code eingebettet und stehen dann im Browser zur Verfügung.

NEXT_PUBLIC_API_URL=https://api.example.com

export default function Page() {
  return <p>API URL: {process.env.NEXT_PUBLIC_API_URL}</p>;
}

Hier wird NEXT_PUBLIC_API_URL während des Build-Prozesses ersetzt und in den JavaScript-Bundle eingebettet, sodass sie im Client verfügbar ist. Änderungen an dieser Variable erfordern immer einen neuen Build.

Beispiel 2: Server-seitige Variablen (ohne NEXT_PUBLIC_)

Auch Variablen ohne NEXT_PUBLIC_ können zur Build-Time benötigt werden, z. B. wenn sie für serverseitige Prozesse wie Datenbankverbindungen, API-Calls oder Static Site Generation (SSG) verwendet werden.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

export async function generateStaticProps() {
  const db = await connectToDb({
    host: process.env.DB_HOST,
    user: process.env.DB_USER,
    password: process.env.DB_PASS,
  });

  const posts = await db.getPosts();
  return { props: { posts } };
}

In diesem Fall wird DB_HOST zur Build-Time benötigt, um die Datenbank zu verbinden und Inhalte vorzubereiten. Diese Variablen bleiben ausschließlich auf dem Server und sind nie im Client sichtbar.

Was passiert zur Runtime?

Zur Runtime stehen Variablen ausschließlich im Node.js-Kontext zur Verfügung, z. B. in serverseitigen API-Routen oder Middleware. Änderungen an diesen Variablen erfordern keinen neuen Build, da sie direkt aus der laufenden Umgebung gelesen werden.

Beispiel:

import { connect } from 'some-database-library';

export async function getDbConnection() {
  return connect({
    host: process.env.DB_HOST,
    user: process.env.DB_USER,
    password: process.env.DB_PASS,
  });
}

Hier wird process.env zur Laufzeit genutzt, um die Verbindung mit der Datenbank herzustellen. Änderungen an der .env-Datei wirken sich sofort nach einem Serverneustart aus.

Unterschiede zwischen Build-Time und Runtime

Typische Fehler bei Build-Time und Runtime

1. Fehlende Server-Variablen zur Build-Time

Server-Variablen wie DB_HOST oder API_KEY können bei der Generierung von statischen Seiten (SSG) benötigt werden. Fehlen diese, führt dies zu Fehlern im Build-Prozess.

Lösung: Stelle sicher, dass alle erforderlichen Variablen vor dem Build definiert sind. Nutze ggf. Tools wie dotenv oder @next/env, um Variablen zu laden.

2. Verwechslung von Build-Time und Runtime

Ein häufiger Fehler ist, dass Entwickler versuchen, Variablen ohne NEXT_PUBLIC_ im Client zu verwenden.

Beispiel (falsch):

export default function Page() {
  return <p>DB Host: {process.env.DB_HOST}</p>;
}

Dieser Code führt zu einem Fehler, da DB_HOST im Client nicht verfügbar ist.

Lösung: Nutze NEXT_PUBLIC_, wenn Variablen im Browser benötigt werden. Server-Variablen bleiben ausschließlich im Node.js-Kontext.

Mit diesem Wissen kannst du sicherstellen, dass deine .env-Variablen korrekt eingesetzt werden – unabhängig davon, ob sie zur Build-Time oder Runtime benötigt werden. Im nächsten Abschnitt werfen wir einen Blick auf typische Fehlerquellen und Best Practices für den Umgang mit .env-Dateien.

5. Typische Fehler und Best Practices

Die Verwendung von .env-Dateien in Next.js ist leistungsstark, kann aber auch leicht zu Fehlern führen, wenn Variablen falsch definiert, gelesen oder verarbeitet werden. In diesem Abschnitt werfen wir einen Blick auf häufige Stolperfallen und zeigen dir, wie du diese mit Best Practices vermeidest.

Typische Fehler

1. Fehlende .env-Datei

Wenn die .env-Datei nicht vorhanden oder falsch benannt ist, können Variablen nicht geladen werden. Dies führt häufig zu unerwartetem Verhalten oder Fehlern wie undefined.

Beispiel (falscher Name):

.local.env // statt .env.local

Lösung: Stelle sicher, dass .env-Dateien korrekt benannt sind und sich im Root-Verzeichnis des Projekts befinden.

2. Sensible Variablen im Client verfügbar

Ein häufiger Sicherheitsfehler ist das versehentliche Freigeben sensibler Daten wie API-Schlüssel oder Datenbank-Passwörter im Client.

Beispiel:

NEXT_PUBLIC_API_KEY=123456789

Problem: NEXT_PUBLIC_API_KEY wird im Client sichtbar und kann von jedem eingesehen werden.

Lösung: Sensible Daten niemals mit NEXT_PUBLIC_ freigeben. Verarbeite diese ausschließlich auf dem Server.

3. Änderungen an .env-Variablen werden ignoriert

Nach Änderungen an einer .env-Datei werden diese nicht automatisch übernommen, insbesondere bei Variablen, die zur Build-Time benötigt werden.

Lösung:

• Bei Änderungen an Build-Time-Variablen: Führe next build erneut aus.
• Bei Runtime-Variablen: Starte den Server neu (next start oder Entwicklungsserver).

4. Nicht validierte Umgebungsvariablen

Wenn .env-Variablen falsch definiert oder unvollständig sind, können Fehler auftreten, die schwer zu debuggen sind.

Beispiel:

DB_HOST=localhost
DB_USER=

Lösung: Validiere .env-Variablen, um sicherzustellen, dass alle benötigten Werte vorhanden und korrekt sind. (Siehe Best Practices.)

5. .env-Dateien in Git-Repository

Das Versionieren von .env-Dateien kann dazu führen, dass sensible Daten wie Passwörter oder API-Schlüssel öffentlich zugänglich werden.

Lösung: Füge .env-Dateien zur .gitignore hinzu, um sie vom Repository auszuschließen:

# .gitignore
.env
.env.local
.env.*.local

Best Practices

1. Konsistente Nutzung von .env-Dateien

• Verwende .env, .env.local, .env.production und ähnliche Dateien entsprechend ihrer Funktion.
• Halte dich an die Ladereihenfolge, um Konflikte zu vermeiden.

2. Umgebungsvariablen sicher validieren

Nutze Validierungsbibliotheken wie Zod, um sicherzustellen, dass alle Variablen korrekt definiert sind:

Beispiel mit Zod:

import "dotenv/config";
import { z } from "zod";

const EnvSchema = z.object({
  DB_HOST: z.string(),
  DB_USER: z.string(),
  DB_PASS: z.string(),
});

export const env = EnvSchema.parse(process.env);

Vorteile der Validierung:

• Sofortiges Feedback, wenn Variablen fehlen oder ungültig sind.
• Robustere Anwendungen, die weniger anfällig für Konfigurationsfehler sind.

3. Sensible Daten sicher handhaben

• Speichere sensible Daten wie API-Schlüssel nur in .env.local-Dateien, die niemals versioniert werden.
• Vermeide es, sensible Variablen im Client zugänglich zu machen (kein NEXT_PUBLIC_).

4. Änderungen durch Tests absichern

Automatisierte Tests stellen sicher, dass deine Anwendung auch bei unterschiedlichen .env-Konfigurationen korrekt funktioniert. Nutze beispielsweise .env.test für Testumgebungen:

# .env.test
DB_HOST=test-db.example.com
DB_USER=testuser
DB_PASS=testpassword

Kombiniere dies mit Tools wie Jest oder Vitest, um sicherzustellen, dass Tests auf konsistenten Umgebungen basieren.

5. Debugging von .env-Variablen

Bei Problemen mit .env-Variablen kannst du folgende Schritte durchführen:

• Gib alle geladenen Variablen aus:

console.log(process.env);  

• Überprüfe, ob die richtige .env-Datei verwendet wird.

Mit diesen Best Practices und der Vermeidung typischer Fehler stellst du sicher, dass deine .env-Variablen zuverlässig und sicher funktionieren. Im nächsten Abschnitt behandeln wir die Validierung von Variablen und deren Integration in den Build- oder Runtime-Prozess.

6. Sicheres Validieren von .env-Variablen

Das Arbeiten mit .env-Dateien birgt eine wesentliche Herausforderung: Fehlerhaft konfigurierte oder fehlende Variablen können zu schwer auffindbaren Fehlern führen. Besonders in größeren Projekten mit mehreren Umgebungen ist es daher wichtig, .env-Variablen zu validieren.

In diesem Abschnitt lernst du, wie du mit der Validierungsbibliothek Zod sicherstellst, dass alle benötigten Umgebungsvariablen vorhanden und korrekt sind.

Warum Validierung wichtig ist

Ohne Validierung können folgende Probleme auftreten:

1. Fehlende Variablen: Deine Anwendung startet möglicherweise nicht korrekt oder stürzt unerwartet ab.
2. Falsche Werte: Eine fehlerhafte Konfiguration (z. B. ein falscher Datenbank-Host) kann zu unerwartetem Verhalten führen.
3. Fehlerhandling: Ohne Validierung wird oft erst zur Laufzeit deutlich, dass eine Variable fehlt – was in Produktion kritisch sein kann.

Durch Validierung kannst du sicherstellen, dass:

• Alle erforderlichen Variablen korrekt gesetzt sind.
• Fehler frühzeitig (beim Start der Anwendung) auffallen.
• Die Anwendung robuster wird.

Validierung mit Zod

Zod ist eine beliebte TypeScript-Validierungsbibliothek, die sich ideal für die Validierung von .env-Variablen eignet. Hier ist ein Beispiel, wie du Zod nutzen kannst, um Variablen sicher zu prüfen.

Beispiel: Validierung einer .env-Datei

Angenommen, deine .env-Datei sieht so aus:

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword
TELEGRAM_TOKEN=abcdef123456

Du kannst mit Zod ein Schema definieren, das sicherstellt, dass diese Variablen vorhanden sind und den erwarteten Datentyp haben:

import "dotenv/config";
import { z } from "zod";

// Schema für die Validierung der Umgebungsvariablen
const EnvSchema = z.object({
  DB_HOST: z.string(),
  DB_USER: z.string(),
  DB_PASS: z.string(),
  TELEGRAM_TOKEN: z.string(),
});

// Validierung der Variablen aus `process.env`
export const env = EnvSchema.parse(process.env);

// Zugriff auf validierte Variablen
console.log("Datenbank-Host:", env.DB_HOST);

Fehlerhandling bei fehlenden Variablen

Wenn eine der Variablen fehlt oder ungültig ist, wirft Zod automatisch einen Fehler. Hier ein Beispiel für die Ausgabe:

ZodError: 
  - DB_HOST is required
  - TELEGRAM_TOKEN must be a string

Das hilft dir, Fehler schnell zu finden und zu beheben.

Optionale Variablen

Falls bestimmte Variablen optional sind, kannst du das im Schema definieren:

const EnvSchema = z.object({
  DB_HOST: z.string(),
  DB_USER: z.string(),
  DB_PASS: z.string(),
  TELEGRAM_TOKEN: z.string().optional(),
});

Wenn die optionale Variable fehlt, gibt Zod undefined zurück. Du kannst dann einen Standardwert setzen:

const token = env.TELEGRAM_TOKEN ?? "default-token";

Validierung in Next.js integrieren

Um sicherzustellen, dass die Validierung immer vor dem Start der Anwendung erfolgt, kannst du die Validierungslogik in eine separate Datei auslagern (z. B. env.ts) und diese frühzeitig in deinem Projekt importieren.

Beispiel für die Integration in eine API-Route:

import { env } from "@/env";

export async function GET() {
  const dbHost = env.DB_HOST; // Bereits validiert
  return  Response.json({ dbHost});
}

Validierung in Tests

Für Tests kannst du ebenfalls Validierung einsetzen, um sicherzustellen, dass Testumgebungen korrekt konfiguriert sind. Nutze eine .env.test-Datei und lade diese in deinem Setup:

import { loadEnvConfig } from "@next/env";
import { EnvSchema } from "@/env";

const projectDir = process.cwd();
loadEnvConfig(projectDir); // Lädt .env.test

// Validierung der Test-Umgebungsvariablen
EnvSchema.parse(process.env);

Best Practices für die Validierung

1. Immer ein Schema verwenden: Definiere explizit, welche Variablen erforderlich sind.
2. Frühzeitige Validierung: Validiere Variablen beim Start der Anwendung, nicht erst zur Laufzeit.
3. Optionale Werte explizit behandeln: Stelle sicher, dass optionale Variablen Standardwerte haben.
4. Fehler klar kommunizieren: Gib aussagekräftige Fehlermeldungen aus, um die Fehlerbehebung zu erleichtern.

Mit Zod kannst du .env-Variablen sicher validieren und deine Anwendung robuster machen.

7. Fazit

Umgebungsvariablen in Next.js sind ein unverzichtbares Werkzeug, um Konfigurationen flexibel und sicher zu verwalten. Sie ermöglichen es, sensible Daten wie API-Schlüssel oder Datenbankverbindungen vom Quellcode zu trennen und gleichzeitig eine konsistente Entwicklungs- und Produktionsumgebung zu gewährleisten.

Zusammenfassung der wichtigsten Punkte

1. Lesezeitpunkt von .env-Variablen
   • Variablen können entweder zur Build-Time oder zur Runtime verwendet werden.
   • Client-seitige Variablen (NEXT_PUBLIC_) sind immer zur Build-Time erforderlich, während serverseitige Variablen sowohl zur Build-Time als auch zur Runtime genutzt werden können.
2. Unterschiede zwischen Build-Time und Runtime
   • Build-Time-Variablen werden während des Build-Prozesses fest in den Code eingebettet und erfordern einen neuen Build bei Änderungen.
   • Runtime-Variablen werden direkt aus der laufenden Umgebung gelesen und wirken sich sofort nach einem Neustart des Servers aus.
3. Sichere Validierung für robuste Anwendungen
   • Mit Tools wie Zod kannst du sicherstellen, dass alle benötigten Variablen vorhanden und korrekt definiert sind. Fehlende oder fehlerhafte Variablen werden frühzeitig erkannt und durch klare Fehlermeldungen kommuniziert.
4. Best Practices für fehlerfreies Arbeiten
   • Nie .env-Dateien versionieren: Nutze .gitignore, um sensible Daten zu schützen.
   • Konsistente Nutzung der .env-Dateien: Halte dich an die Ladereihenfolge und benutze spezifische Dateien wie .env.local für lokale Konfigurationen.
   • Tests und Debugging: Verifiziere .env-Konfigurationen mit automatisierten Tests und nutze Debugging-Tools, um Probleme schnell zu identifizieren.

Empfehlung

Für eine reibungslose Entwicklung und einen stabilen Betrieb deiner Anwendungen empfehlen sich folgende Maßnahmen:

• Konsistente Nutzung: Setze .env-Variablen gezielt ein und trenne Konfigurationen klar nach Umgebung.
• Validierung: Stelle sicher, dass alle Variablen korrekt definiert sind, um unerwartete Fehler zu vermeiden.
• Tests: Sichere deine Konfigurationen durch automatisierte Tests ab, insbesondere für spezifische Umgebungen wie Produktion oder Tests.

Wenn du diese Prinzipien befolgst, kannst du nicht nur sicherstellen, dass deine Anwendung reibungslos funktioniert, sondern auch deine Entwicklungsprozesse effizienter gestalten.