Umgebungsvariablen und Konfiguration in Node.js

Früher oder später kommt jedes Node.js-Projekt an den Punkt, an dem du Konfigurationswerte brauchst: eine Datenbank-URL, einen API-Schlüssel oder den Port, auf dem dein Server läuft. Diese Werte fest in den Quellcode zu schreiben, ist eine schlechte Idee. In diesem Beitrag zeige ich dir, wie du Umgebungsvariablen nutzt, um deine Anwendung sauber und sicher zu konfigurieren.

Was sind Umgebungsvariablen?

Umgebungsvariablen sind Schlüssel-Wert-Paare, die das Betriebssystem deinem Prozess zur Verfügung stellt. Sie leben außerhalb deines Codes und können sich je nach Umgebung unterscheiden, etwa zwischen deinem lokalen Rechner, einem Testserver und der Produktion. In Node.js erreichst du sie über das globale Objekt process.env.

// Eine Umgebungsvariable lesen
const port = process.env.PORT;
console.log(`Server soll auf Port ${port} laufen`);

// Mit einem Standardwert, falls die Variable nicht gesetzt ist
const dbHost = process.env.DB_HOST || 'localhost';
console.log(`Datenbank-Host: ${dbHost}`);

Alle Werte in process.env sind Strings. Wenn du eine Zahl brauchst, musst du sie selbst umwandeln.

Variablen im Terminal setzen

Du kannst eine Variable direkt beim Start deines Programms übergeben. Unter Linux und macOS sieht das so aus:

# Variable nur für diesen einen Aufruf setzen
PORT=4000 DB_HOST=db.example.com node app.js

# Oder dauerhaft für die aktuelle Shell exportieren
export PORT=4000
node app.js

Unter Windows funktioniert das Setzen etwas anders, weshalb viele Teams auf das npm-Paket cross-env setzen, um plattformübergreifend einheitlich zu bleiben.

Die .env-Datei mit dotenv

Variablen jedes Mal von Hand zu tippen ist mühsam. Stattdessen legst du sie in einer Datei namens .env ab und lädst sie mit dem populären Paket dotenv.

# Paket installieren
npm install dotenv

Deine .env-Datei könnte so aussehen:

PORT=4000
DB_HOST=localhost
DB_PASSWORD=geheim123
API_KEY=sk_live_abc123

Ganz am Anfang deiner Anwendung lädst du die Datei einmal, danach stehen alle Werte in process.env bereit:

// Muss möglichst früh passieren
require('dotenv').config();

const config = {
  port: Number(process.env.PORT) || 3000,
  dbHost: process.env.DB_HOST,
  dbPassword: process.env.DB_PASSWORD,
};

console.log(`Verbinde mit ${config.dbHost} auf Port ${config.port}`);

Niemals Secrets ins Git-Repository

Das ist die wichtigste Regel: Deine .env-Datei enthält Passwörter und Schlüssel und darf niemals in deinem Repository landen. Trage sie deshalb in deine .gitignore ein.

# .gitignore
.env
node_modules/

Damit andere Entwickler trotzdem wissen, welche Variablen benötigt werden, legst du eine Vorlage namens .env.example an, die nur die Schlüssel ohne echte Werte enthält und ins Repository darf.

Konfiguration validieren

Fehlt eine wichtige Variable, sollte dein Programm sofort und mit klarer Meldung abbrechen, statt später kryptisch zu scheitern. Eine kleine Prüfung beim Start hilft enorm.

require('dotenv').config();

const erforderlich = ['DB_HOST', 'DB_PASSWORD', 'API_KEY'];

for (const name of erforderlich) {
  if (!process.env[name]) {
    console.error(`Fehler: Umgebungsvariable ${name} fehlt!`);
    process.exit(1);
  }
}

console.log('Alle erforderlichen Variablen sind gesetzt.');

So bekommst du beim Start sofort Feedback, wenn die Konfiguration unvollständig ist.

Fazit

Umgebungsvariablen trennen deine Konfiguration sauber vom Code. Du liest sie über process.env, verwaltest sie lokal bequem mit einer .env-Datei und dotenv und hältst Secrets dank .gitignore aus deinem Repository heraus. Mit einer kleinen Validierung beim Start stellst du außerdem sicher, dass deine App nur mit vollständiger Konfiguration startet. Diese Bausteine gehören in jedes professionelle Node.js-Projekt.