Umgebungsvariablen

Next.js verfügt über integrierte Unterstützung für Umgebungsvariablen, die Ihnen Folgendes ermöglichen:

• Laden von Umgebungsvariablen mit .env
• Bündeln von Umgebungsvariablen für den Browser durch Voranstellen von NEXT_PUBLIC_

Laden von Umgebungsvariablen

Next.js unterstützt standardmäßig das Laden von Umgebungsvariablen aus .env*-Dateien in process.env.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Dies lädt process.env.DB_HOST, process.env.DB_USER und process.env.DB_PASS automatisch in die Node.js-Umgebung und ermöglicht deren Verwendung in Next.js-Datenabfragemethoden und API-Routen.

Zum Beispiel bei Verwendung von getStaticProps:

export async function getStaticProps() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

Laden von Umgebungsvariablen mit @next/env

Wenn Sie Umgebungsvariablen außerhalb der Next.js-Laufzeit laden müssen, z. B. in einer Root-Konfigurationsdatei für ein ORM oder einen Testrunner, können Sie das Paket @next/env verwenden.

Dieses Paket wird intern von Next.js verwendet, um Umgebungsvariablen aus .env*-Dateien zu laden.

Um es zu verwenden, installieren Sie das Paket und verwenden Sie die Funktion loadEnvConfig, um die Umgebungsvariablen zu laden:

npm install @next/env

import { loadEnvConfig } from '@next/env'
 
const projectDir = process.cwd()
loadEnvConfig(projectDir)

Dann können Sie die Konfiguration bei Bedarf importieren. Zum Beispiel:

import './envConfig.ts'
 
export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})

Referenzieren anderer Variablen

Next.js erweitert automatisch Variablen, die $ verwenden, um auf andere Variablen zu verweisen, z. B. $VARIABLE in Ihren .env*-Dateien. Dies ermöglicht das Referenzieren anderer Geheimnisse. Zum Beispiel:

TWITTER_USER=nextjs
TWITTER_URL=https://x.com/$TWITTER_USER

In diesem Beispiel würde process.env.TWITTER_URL auf https://x.com/nextjs gesetzt werden.

Hinweis: Wenn Sie eine Variable mit einem $ im tatsächlichen Wert verwenden müssen, muss sie mit Escapezeichen versehen werden, z. B. \$.

Bündeln von Umgebungsvariablen für den Browser

Nicht-NEXT_PUBLIC_-Umgebungsvariablen sind nur in der Node.js-Umgebung verfügbar, d. h. sie sind nicht für den Browser zugänglich (der Client läuft in einer anderen Umgebung).

Um den Wert einer Umgebungsvariablen im Browser verfügbar zu machen, kann Next.js einen Wert zum Build-Zeitpunkt in das an den Client gesendete JS-Bundle "inline" einfügen, wobei alle Verweise auf process.env.[variable] durch einen fest codierten Wert ersetzt werden. Um dies zu erreichen, müssen Sie die Variable einfach mit NEXT_PUBLIC_ voranstellen. Zum Beispiel:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

Dies weist Next.js an, alle Verweise auf process.env.NEXT_PUBLIC_ANALYTICS_ID in der Node.js-Umgebung durch den Wert aus der Umgebung, in der Sie next build ausführen, zu ersetzen, sodass Sie ihn in Ihrem gesamten Code verwenden können. Er wird in das an den Browser gesendete JavaScript inline eingefügt.

Hinweis: Nach dem Build wird Ihre App nicht mehr auf Änderungen dieser Umgebungsvariablen reagieren. Wenn Sie zum Beispiel eine Heroku-Pipeline verwenden, um in einer Umgebung erstellte Slugs in eine andere Umgebung zu übertragen, oder wenn Sie ein einzelnes Docker-Image zur Bereitstellung in mehreren Umgebungen erstellen und bereitstellen, werden alle NEXT_PUBLIC_-Variablen mit dem beim Build ausgewerteten Wert eingefroren. Das bedeutet, diese Werte müssen beim Projektbuild entsprechend festgelegt werden. Wenn Sie Zugriff auf Laufzeit-Umgebungswerte benötigen, müssen Sie einen eigenen API-Endpunkt einrichten, um sie dem Client bereitzustellen (bei Bedarf oder während der Initialisierung).

import setupAnalyticsService from '../lib/my-analytics-service'
 
// 'NEXT_PUBLIC_ANALYTICS_ID' kann hier verwendet werden, da es mit 'NEXT_PUBLIC_' vorangestellt ist.
// Es wird zum Build-Zeitpunkt zu `setupAnalyticsService('abcdefghijk')` transformiert.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
 
function HomePage() {
  return <h1>Hallo Welt</h1>
}
 
export default HomePage

Beachten Sie, dass dynamische Aufrufe nicht inline eingefügt werden, wie zum Beispiel:

// Dies wird NICHT inline eingefügt, da eine Variable verwendet wird
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])
 
// Dies wird NICHT inline eingefügt, da eine Variable verwendet wird
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

Laufzeit-Umgebungsvariablen

Next.js kann sowohl Build-Zeit- als auch Laufzeit-Umgebungsvariablen unterstützen.

Standardmäßig sind Umgebungsvariablen nur auf dem Server verfügbar. Um eine Umgebungsvariable für den Browser verfügbar zu machen, muss sie mit NEXT_PUBLIC_ vorangestellt werden. Diese öffentlichen Umgebungsvariablen werden jedoch während next build in das JavaScript-Bundle inline eingefügt.

Um Laufzeit-Umgebungsvariablen zu lesen, empfehlen wir die Verwendung von getServerSideProps oder schrittweise Einführung des App Routers.

Dies ermöglicht die Verwendung eines einzelnen Docker-Images, das durch verschiedene Umgebungen mit unterschiedlichen Werten befördert werden kann.

Hinweis:

• Sie können Code beim Server-Start mit der Funktion register ausführen.
• Wir empfehlen nicht die Verwendung der Option runtimeConfig, da diese nicht mit dem Standalone-Ausgabemodus funktioniert. Stattdessen empfehlen wir die schrittweise Einführung des App Routers.

Standard-Umgebungsvariablen

Typischerweise wird nur die .env*-Datei benötigt. Manchmal möchten Sie jedoch Standardwerte für die development (next dev)- oder production (next start)-Umgebung hinzufügen.

Next.js ermöglicht es Ihnen, Standardwerte in .env (alle Umgebungen), .env.development (Entwicklungsumgebung) und .env.production (Produktionsumgebung) festzulegen.

Hinweis: .env-, .env.development- und .env.production-Dateien sollten in Ihr Repository einbezogen werden, da sie Standardwerte definieren. Alle .env-Dateien sind standardmäßig in .gitignore ausgeschlossen, sodass Sie sich für die Einbindung dieser Werte in Ihr Repository entscheiden können.

Umgebungsvariablen auf Vercel

Bei der Bereitstellung Ihrer Next.js-Anwendung auf Vercel können Umgebungsvariablen in den Projekteinstellungen konfiguriert werden.

Alle Arten von Umgebungsvariablen sollten dort konfiguriert werden. Auch Umgebungsvariablen, die in der Entwicklung verwendet werden – die anschließend auf Ihr lokales Gerät heruntergeladen werden können.

Wenn Sie Entwicklungsumgebungsvariablen konfiguriert haben, können Sie diese mit folgendem Befehl in eine .env.local für die Verwendung auf Ihrem lokalen Rechner ziehen:

vercel env pull

Hinweis: Bei der Bereitstellung Ihrer Next.js-Anwendung auf Vercel werden Ihre Umgebungsvariablen in .env*-Dateien nicht für die Edge-Laufzeit verfügbar gemacht, es sei denn, ihre Namen beginnen mit NEXT_PUBLIC_. Wir empfehlen dringend, Ihre Umgebungsvariablen in den Projekteinstellungen zu verwalten, von wo aus alle Umgebungsvariablen verfügbar sind.

Test-Umgebungsvariablen

Neben den Umgebungen development und production gibt es eine dritte Option: test. Genauso wie Sie Standardwerte für Entwicklungs- oder Produktionsumgebungen festlegen können, können Sie dies auch mit einer .env.test-Datei für die testing-Umgebung tun (obwohl diese nicht so häufig verwendet wird wie die beiden vorherigen). Next.js wird keine Umgebungsvariablen aus .env.development oder .env.production in der testing-Umgebung laden.

Dies ist nützlich bei Tests mit Tools wie jest oder cypress, bei denen Sie spezifische Umgebungsvariablen nur für Testzwecke setzen müssen. Standardwerte für Tests werden geladen, wenn NODE_ENV auf test gesetzt ist, obwohl Sie dies normalerweise nicht manuell machen müssen, da Testtools dies für Sie übernehmen.

Es gibt einen kleinen Unterschied zwischen der test-Umgebung und den Umgebungen development und production, den Sie beachten müssen: .env.local wird nicht geladen, da Sie erwarten, dass Tests für jeden die gleichen Ergebnisse liefern. Auf diese Weise verwendet jede Testausführung die gleichen Umgebungsstandardwerte über verschiedene Ausführungen hinweg, indem Ihr .env.local ignoriert wird (das dazu gedacht ist, die Standardeinstellung zu überschreiben).

Hinweis: Ähnlich wie bei Standard-Umgebungsvariablen sollte die .env.test-Datei in Ihr Repository einbezogen werden, aber .env.test.local nicht, da .env*.local durch .gitignore ignoriert werden sollen.

Beim Ausführen von Unit-Tests können Sie sicherstellen, dass Ihre Umgebungsvariablen genauso geladen werden wie von Next.js, indem Sie die loadEnvConfig-Funktion aus dem @next/env-Paket nutzen.

// Das Folgende kann in einer Jest-Global-Setup-Datei oder ähnlichem für Ihre Testeinrichtung verwendet werden
import { loadEnvConfig } from '@next/env'
 
export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

Ladereihenfolge von Umgebungsvariablen

Umgebungsvariablen werden in der folgenden Reihenfolge gesucht, wobei die Suche stoppt, sobald die Variable gefunden wurde:

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local (Wird nicht geprüft, wenn NODE_ENV test ist.)
4. .env.$(NODE_ENV)
5. .env

Wenn NODE_ENV beispielsweise development ist und Sie eine Variable sowohl in .env.development.local als auch in .env definieren, wird der Wert aus .env.development.local verwendet.

Hinweis: Die erlaubten Werte für NODE_ENV sind production, development und test.

Gut zu wissen

• Wenn Sie ein /src-Verzeichnis verwenden, sollten .env.*-Dateien im Stammverzeichnis Ihres Projekts verbleiben.
• Wenn die Umgebungsvariable NODE_ENV nicht zugewiesen ist, weist Next.js automatisch development beim Ausführen des next dev-Befehls oder production für alle anderen Befehle zu.

Versionshistorie