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

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,
  })
  // ...
}

Verweisen 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.

Gut zu wissen: Wenn Sie ein Dollarzeichen ($) im tatsächlichen Wert benötigen, muss es mit einem Backslash (\) maskiert werden, z.B. \$.

Bündeln von Umgebungsvariablen für den Browser

Umgebungsvariablen ohne das Präfix NEXT_PUBLIC_ sind nur in der Node.js-Umgebung verfügbar, d.h. sie sind für den 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 JS-Bundle einfügen, das an den Client geliefert wird, und alle Verweise auf process.env.[variable] durch einen hartkodierten Wert ersetzen. 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, sodass Sie ihn überall in Ihrem Code verwenden können. Er wird in jeden an den Browser gesendeten JavaScript-Code eingefügt.

Hinweis: Nach dem Build reagiert Ihre App nicht mehr auf Änderungen an diesen 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 für mehrere Umgebungen erstellen und bereitstellen, werden alle NEXT_PUBLIC_-Variablen mit dem zum Build-Zeitpunkt ausgewerteten Wert eingefroren. Daher müssen diese Werte beim Erstellen des Projekts entsprechend gesetzt werden. Wenn Sie auf Laufzeit-Umgebungswerte zugreifen müssen, müssen Sie Ihre 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 eingefügt werden, wie z.B.:

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

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

Standard-Umgebungsvariablen

In der Regel wird nur eine .env.local-Datei benötigt. Manchmal möchten Sie jedoch möglicherweise einige 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.

Gut zu wissen: .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 – welche auf Ihr lokales Gerät heruntergeladen werden können.

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

vercel env pull .env.local

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 test-Umgebung tun (obwohl diese nicht so häufig verwendet wird wie die beiden vorherigen). Next.js lädt in der test-Umgebung keine Umgebungsvariablen aus .env.development oder .env.production.

Dies ist nützlich, wenn Sie Tests mit Tools wie jest oder cypress durchfü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 übernehmen.

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

Gut zu wissen: Ä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 Funktion loadEnvConfig aus dem Paket @next/env verwenden.

// 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 den folgenden Orten in der angegebenen Reihenfolge gesucht, wobei die Suche beendet wird, 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 aus .env.development.local verwendet.

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

Gut zu wissen

• 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.