Verwendung von Umgebungsvariablen in Next.js

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

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

Warnung: Die Standardvorlage create-next-app stellt sicher, dass alle .env-Dateien zu Ihrer .gitignore hinzugefügt werden. Sie sollten diese Dateien fast nie in Ihr Repository einchecken.

Laden von Umgebungsvariablen

Next.js bietet integrierte Unterstützung für das Laden von Umgebungsvariablen aus .env*-Dateien 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

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

# oder mit `\n` innerhalb doppelter 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,
  })
  // ...
}

Laden von Umgebungsvariablen mit @next/env

Wenn Sie Umgebungsvariablen außerhalb der Next.js-Laufzeitumgebung laden müssen, z.B. in einer 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 dort importieren, wo sie benötigt wird. 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 es Ihnen, auf andere Geheimnisse zu verweisen. Beispiel:

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

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

Gut zu wissen: Wenn Sie eine Variable mit einem $ im tatsächlichen Wert verwenden müssen, muss diese mit \ escaped werden, z.B. \$.

Bündeln von Umgebungsvariablen für den Browser

Nicht mit NEXT_PUBLIC_ präfixierte 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 zur Build-Zeit in das JS-Bundle einfügen, das an den Client geliefert wird, und alle Referenzen auf process.env.[variable] durch einen hartkodierten Wert ersetzen. Um dies zu erreichen, müssen Sie der Variablen einfach das Präfix NEXT_PUBLIC_ voranstellen. Beispiel:

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

Dies weist Next.js an, alle Referenzen 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 JavaScript-Code eingefügt, der an den Browser gesendet wird.

Hinweis: Nach dem Build reagiert Ihre App nicht mehr auf Änderungen dieser Umgebungsvariablen. Wenn Sie beispielsweise eine Heroku-Pipeline verwenden, um Slugs, die in einer Umgebung erstellt wurden, in eine andere Umgebung zu verschieben, oder wenn Sie ein einzelnes Docker-Image in mehreren Umgebungen bereitstellen, werden alle NEXT_PUBLIC_-Variablen mit dem Wert eingefroren, der zur Build-Zeit ausgewertet wurde. Daher müssen diese Werte 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 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)

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_ präfixiert werden. Diese öffentlichen Umgebungsvariablen werden jedoch während next build in das JavaScript-Bundle eingefügt.

Sie können Umgebungsvariablen sicher auf dem Server während des dynamischen Renderings lesen:

import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // Cookies, Header und andere Dynamic APIs
  // werden ebenfalls dynamisches Rendering erzwingen, was bedeutet,
  // dass diese Umgebungsvariable zur Laufzeit ausgewertet wird
  const value = process.env.MY_VALUE
  // ...
}

Dies ermöglicht es Ihnen, ein einziges Docker-Image zu verwenden, das in mehreren Umgebungen mit unterschiedlichen Werten bereitgestellt werden kann.

Gut zu wissen:

• 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 Migration zum App-Router, wenn Sie diese Funktion benötigen.

Test-Umgebungsvariablen

Neben den Umgebungen development und production gibt es eine dritte Option: test. Genau 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 setzen 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 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-Dateien über .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 NODE_ENV beispielsweise 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 .env.*-Dateien im Stammverzeichnis Ihres Projekts bleiben.
• Wenn die Umgebungsvariable NODE_ENV nicht gesetzt ist, setzt Next.js automatisch development beim Ausführen des Befehls next dev und production für alle anderen Befehle.

Versionsverlauf