Umgebungsvariablen

Next.js bietet integrierte Unterstützung für Umgebungsvariablen, die Ihnen folgende Möglichkeiten bietet:

• Verwendung von .env.local zum Laden von Umgebungsvariablen
• Bündeln von Umgebungsvariablen für den Browser durch das Präfix NEXT_PUBLIC_

Laden von Umgebungsvariablen

Next.js bietet integrierte Unterstützung für das Laden von Umgebungsvariablen aus .env.local in process.env.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Hinweis: Next.js unterstützt auch mehrzeilige Variablen in Ihren .env*-Dateien:

# .env.local

# Sie können mit Zeilenumbrüchen schreiben
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

# oder mit `\n` innerhalb von Anführungszeichen
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

Hinweis: Wenn Sie einen /src-Ordner verwenden, beachten Sie bitte, dass Next.js die .env-Dateien nur aus dem übergeordneten Ordner und nicht aus dem /src-Ordner lädt. Dadurch werden process.env.DB_HOST, process.env.DB_USER und process.env.DB_PASS automatisch in die Node.js-Umgebung geladen, sodass Sie sie in Route Handlers verwenden können.

Beispiel:

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

Verweise auf andere Variablen

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

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

Im obigen Beispiel würde process.env.TWITTER_URL auf https://twitter.com/nextjs gesetzt werden.

Wissenswert: Wenn Sie ein $ im tatsächlichen Wert einer Variable benötigen, muss es mit einem Backslash (\) escaped werden, z.B. \$.

Bündeln von Umgebungsvariablen für den Browser

Umgebungsvariablen ohne NEXT_PUBLIC_-Präfix sind nur in der Node.js-Umgebung verfügbar, d.h. sie sind im Browser nicht zugänglich (der Client läuft in einer anderen Umgebung).

Um den Wert einer Umgebungsvariablen im Browser verfügbar zu machen, kann Next.js den Wert zur Build-Zeit in das JavaScript-Bundle einfügen, das an den Client geliefert wird. Dabei werden alle Verweise auf process.env.[variable] durch einen hartkodierten Wert ersetzt. Um dies zu ermöglichen, müssen Sie der Variablen einfach das Präfix NEXT_PUBLIC_ voranstellen. 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 zu ersetzen, in der Sie next build ausführen. Dadurch können Sie die Variable überall in Ihrem Code verwenden. Sie wird in jedes an den Browser gesendete JavaScript eingebettet.

Hinweis: Nach dem Build reagiert Ihre App nicht mehr auf Änderungen dieser Umgebungsvariablen. Wenn Sie beispielsweise eine Heroku-Pipeline verwenden, um Slugs aus einer Umgebung in eine andere zu übertragen, oder wenn Sie ein einzelnes Docker-Image in mehreren Umgebungen bereitstellen, werden alle NEXT_PUBLIC_-Variablen mit den zur Build-Zeit ausgewerteten Werten eingefroren. Diese Werte müssen daher beim Build des Projekts entsprechend gesetzt werden. Wenn Sie Zugriff auf Laufzeit-Umgebungsvariablen benötigen, müssen Sie eine eigene API einrichten, um sie dem Client bereitzustellen (entweder 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_' präfixiert ist.
// Es wird zur Build-Zeit in `setupAnalyticsService('abcdefghijk')` umgewandelt.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

Beachten Sie, dass dynamische Abfragen nicht eingebettet werden, wie z.B.:

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

// Dies wird NICHT eingebettet, da eine Variable verwendet wird
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

Laufzeit-Umgebungsvariablen

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

Standardmäßig sind Umgebungsvariablen nur auf dem Server verfügbar. Um eine Umgebungsvariable im Browser verfügbar zu machen, muss sie mit NEXT_PUBLIC_ präfixiert werden. Diese öffentlichen Umgebungsvariablen werden jedoch während next build in das JavaScript-Bundle eingebettet.

Um Laufzeit-Umgebungsvariablen zu lesen, empfehlen wir die Verwendung von getServerSideProps oder die schrittweise Einführung des App-Routers. Mit dem App-Router können Sie Umgebungsvariablen sicher auf dem Server während des dynamischen Renderings lesen. Dies ermöglicht die Verwendung eines einzelnen Docker-Images, das in mehreren Umgebungen mit unterschiedlichen Werten bereitgestellt werden kann.

import { unstable_noStore as noStore } from 'next/cache'

export default function Component() {
  noStore()
  // cookies(), headers() und andere dynamische Funktionen
  // aktivieren ebenfalls dynamisches Rendering, was bedeutet,
  // dass diese Umgebungsvariable zur Laufzeit ausgewertet wird
  const value = process.env.MY_VALUE
  // ...
}

Wissenswert:

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

Standard-Umgebungsvariablen

In der Regel ist nur eine .env.local-Datei erforderlich. Manchmal möchten Sie jedoch möglicherweise Standardwerte für die development- (next dev) oder production- (next start) Umgebung festlegen.

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

.env.local überschreibt immer die festgelegten Standardwerte.

Wissenswert: .env, .env.development und .env.production sollten in Ihrem Repository enthalten sein, da sie Standardwerte definieren. .env*.local sollte zu .gitignore hinzugefügt werden, da diese Dateien ignoriert werden sollen. .env.local ist der Ort, an dem Geheimnisse gespeichert werden können.

Umgebungsvariablen auf Vercel

Wenn Sie Ihre Next.js-Anwendung auf Vercel bereitstellen, können Umgebungsvariablen in den Projekteinstellungen konfiguriert werden.

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

Wenn Sie Entwicklungsumgebungsvariablen konfiguriert haben, können Sie sie mit dem folgenden Befehl in eine .env.local-Datei herunterladen, um sie auf Ihrem lokalen Gerät zu verwenden:

vercel env pull .env.local

Wissenswert: Wenn Sie Ihre Next.js-Anwendung auf Vercel bereitstellen, werden Ihre Umgebungsvariablen in .env*-Dateien nicht für die Edge Runtime verfügbar gemacht, es sei denn, ihr Name ist mit NEXT_PUBLIC_ präfixiert. Wir empfehlen dringend, Ihre Umgebungsvariablen stattdessen in den Projekteinstellungen zu verwalten, von wo aus alle Umgebungsvariablen verfügbar sind.

Test-Umgebungsvariablen

Neben den development- und production-Umgebungen gibt es eine dritte Option: test. Ähnlich wie Sie Standardwerte für Entwicklungs- oder Produktionsumgebungen festlegen können, können Sie dies auch mit einer .env.test-Datei für die test-Umgebung tun (obwohl diese nicht so verbreitet ist wie die ersten beiden). Next.js lädt keine Umgebungsvariablen aus .env.development oder .env.production in der test-Umgebung.

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

Es gibt einen kleinen Unterschied zwischen der test-Umgebung und den development- und production-Umgebungen, den Sie beachten sollten: .env.local wird nicht geladen, da Sie erwarten, dass Tests für alle Benutzer die gleichen Ergebnisse liefern. Auf diese Weise verwendet jede Testausführung die gleichen Standardwerte für die Umgebung, indem Ihre .env.local ignoriert wird (die dazu gedacht ist, die Standardwerte zu überschreiben).

Wissenswert: Ähnlich wie bei Standard-Umgebungsvariablen sollte die .env.test-Datei in Ihrem Repository enthalten sein, aber .env.test.local nicht, da .env*.local durch .gitignore ignoriert werden sollen.

Während Sie Unit-Tests ausführen, können Sie sicherstellen, dass Ihre Umgebungsvariablen auf die gleiche Weise geladen werden wie Next.js, indem Sie die loadEnvConfig-Funktion aus dem @next/env-Paket verwenden.

// Das Folgende kann in einer Jest global setup-Datei oder ähnlichem für Ihre Testumgebung verwendet werden
import { loadEnvConfig } from '@next/env'

export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

Ladereihenfolge von Umgebungsvariablen

Umgebungsvariablen werden in den folgenden Orten in der angegebenen Reihenfolge gesucht, wobei die Suche stoppt, sobald die Variable gefunden wurde.

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

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

Wissenswert: Die zulässigen Werte für NODE_ENV sind production, development und test.

Wissenswert

• Wenn Sie ein /src-Verzeichnis verwenden, sollten die .env.*-Dateien im Stammverzeichnis Ihres Projekts bleiben.
• Wenn die Umgebungsvariable NODE_ENV nicht zugewiesen ist, weist Next.js automatisch development zu, wenn der Befehl next dev ausgeführt wird, oder production für alle anderen Befehle.

Versionsverlauf