Node.js process.env: Umgebungsvariablen lesen

process.env ist ein Objekt mit einer Eigenschaft pro Umgebungsvariable, die die Shell an dein Node.js-Programm übergeben hat: process.env.PORT, process.env.DATABASE_URL und so weiter. Eine Variable, die nicht gesetzt wurde, ist undefined, und eine gesetzte Variable ist immer ein String. Lies sie einmal beim Start, gib ihr einen Standardwert und wandle sie in den Typ um, den du brauchst.

// The shell normally sets these: PORT=8080 APP_NAME=shop node index.js
process.env.PORT = '8080';
process.env.APP_NAME = 'shop';

const port = Number(process.env.PORT ?? 3000);
const name = process.env.APP_NAME ?? 'my-app';
const region = process.env.REGION ?? 'eu-west';

console.log(name, 'on port', port, 'in', region);
console.log(typeof process.env.PORT, typeof port);

Es hat shop on port 8080 in eu-west ausgegeben (REGION wurde nie gesetzt, also hat sein Standardwert übernommen), dann string number: Die Variable ist Text, bis Number() sie umwandelt. Lösch die ersten beiden Zuweisungen und führ es noch einmal aus, um jeden Standardwert zu sehen.

Umgebungsvariablen in der Shell setzen

Die Variablen kommen von dort, wo Node.js gestartet wird. In einem Terminal:

// macOS and Linux: for one command
PORT=8080 NODE_ENV=production node app.js

// macOS and Linux: for the rest of the terminal session
export PORT=8080

// Windows PowerShell
$env:PORT = "8080"; node app.js

// Windows cmd.exe
set PORT=8080
node app.js

Hosting-Plattformen (Heroku, Render, Vercel, Docker, Kubernetes) haben eine Einstellungsseite oder eine Datei für dasselbe; dein Code liest sie auf die gleiche Weise.

Alles ist ein String

Daher kommen die meisten process.env-Bugs. 'false' und '0' sind nicht leere Strings, also truthy:

// The shell normally sets this: DEBUG=false node index.js
process.env.DEBUG = 'false';

if (process.env.DEBUG) {
    console.log('naive check: debug is ON');
}

const debug = process.env.DEBUG === 'true';
console.log('correct check: debug is', debug ? 'ON' : 'OFF');

Die naive Prüfung hat debug is ON für eine Variable mit dem Wert false ausgegeben, vergleich also mit genau dem String, den du erwartest. Bei Zahlen macht Number(process.env.X) aus einem fehlenden Wert NaN, setz den Standardwert also vor der Umwandlung, wie im ersten Beispiel mit ??.

NODE_ENV

NODE_ENV ist eine Konvention, kein Feature von Node.js: Node.js setzt es nie. Bibliotheken lesen es. Express zum Beispiel blendet Stack Traces auf Fehlerseiten aus, wenn es production ist, und viele Tools überspringen Prüfungen, die nur für die Entwicklung gedacht sind.

// The shell normally sets this: NODE_ENV=production node index.js
process.env.NODE_ENV = 'production';

const isProduction = process.env.NODE_ENV === 'production';

console.log('mode:', process.env.NODE_ENV);
console.log('verbose logs:', !isProduction);

Es hat mode: production und verbose logs: false ausgegeben; ändere 'production' in 'development', und die zweite Zeile dreht sich um. Bleib bei production, development und test, weil Bibliotheken genau diese Wörter prüfen.

.env-Dateien: --env-file und dotenv

Jede Variable vor node zu tippen, nervt auf Dauer. Eine .env-Datei hält sie in deinem Projektordner, eine pro Zeile:

// .env
PORT=8080
DATABASE_URL=postgres://localhost/shop
API_KEY=dev-key-123

Node.js 20.6 und neuer lesen sie mit einem Flag, ohne Paket:

node --env-file=.env app.js

Bei älteren Versionen, oder wenn du es lieber magst, installierst du das Paket dotenv (npm install dotenv) und lädst es ganz oben in deiner Einstiegsdatei, bevor irgendein Code process.env liest:

require('dotenv').config(); // copies .env into process.env

console.log(process.env.PORT); // 8080

Keins von beiden überschreibt eine Variable, die in der Shell schon gesetzt ist, die Einstellungen der Produktion gewinnen also gegenüber der Datei.

Bei fehlenden Variablen früh abbrechen

Eine fehlende Datenbank-URL sollte das Programm beim Start mit einer klaren Meldung stoppen, nicht eine Stunde später bei der ersten Anfrage abstürzen:

// The shell normally sets these
process.env.DATABASE_URL = 'postgres://localhost/shop';

const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter((key) => !process.env[key]);

if (missing.length > 0) {
    console.log('Missing environment variables:', missing.join(', '));
} else {
    console.log('Config OK');
}

Es hat Missing environment variables: API_KEY ausgegeben; füg oben process.env.API_KEY = 'test'; hinzu, und es gibt Config OK aus. In einem echten Programm folgt auf die Meldung process.exit(1), weil ein Exit-Code ungleich null für ein Deploy-Skript oder eine Container-Plattform das Zeichen ist, dass der Start fehlgeschlagen ist.

Nie Geheimnisse committen

Trag .env an dem Tag in .gitignore ein, an dem du sie anlegst. Committe stattdessen eine .env.example mit den Variablennamen und Fake-Werten, damit andere wissen, was sie setzen müssen. Ein Schlüssel, der jemals in ein Repository gepusht wurde, gilt als geleakt und muss ersetzt werden, auch wenn du den Commit später löschst.