mitmario.dev

Umgebungsvariablen

Node.js Sandbox 3 Min Lesezeit 3 BeispieleLektion 2 von 7

Dein Programm soll auf drei Rechnern laufen, auf deinem, auf einem Testsystem und in der Produktion. Überall gilt eine andere Datenbankadresse, ein anderer Port, ein anderer Schlüssel für einen fremden Dienst. Der Code soll trotzdem überall derselbe sein, Zeichen für Zeichen. Sonst hast du drei Fassungen, und eine davon ist immer die falsche.

Argumente sind für das, was sich bei jedem Aufruf ändert. Für das, was sich je Ort ändert, gibt es einen zweiten Weg.

Das Fach, in das die Umgebung ihre Werte legt

process.env ist ein Objekt mit allem, was die Umgebung deinem Prozess mitgegeben hat. Auf der Kommandozeile schreibst du die Werte vor den Befehl:

PORT=8080 node start.mjs

Ein Wert mit Standardwert
const PORT = Number(process.env.PORT ?? 3000);
const umgebung = process.env.NODE_ENV ?? "development";

console.log("Port:", PORT);
console.log("Typ des Rohwerts:", typeof process.env.PORT);
console.log("Umgebung:", umgebung);

So wird auch dieses Beispiel gestartet, mit PORT=8080 davor.

Obwohl dort eine Zahl steht, ist typeof process.env.PORT gleich string und nicht number.

Das ?? 3000 fängt den Fall ab, dass niemand einen Port gesetzt hat. Das Programm soll auch ohne gesetzte Umgebung starten. Sonst müsstest du auf deinem eigenen Rechner vor jedem Start alle Werte von Hand setzen, und das macht niemand lange mit.

Derselbe Code ohne gesetzten Port
const PORT = Number(process.env.PORT ?? 3000);
const umgebung = process.env.NODE_ENV ?? "development";

console.log("Port:", PORT);
console.log("Typ des Rohwerts:", typeof process.env.PORT);
console.log("Umgebung:", umgebung);

Es ist dieselbe Datei, unverändert, nur ohne PORT=8080 davor. Eine nicht gesetzte Variable ist undefined, und dann springt der Standardwert ein. Beim NODE_ENV siehst du das schon im ersten Beispiel. Gesetzt ist dort nur der Port. Also steht bei der Umgebung development.

In der Befehlsleiste stehen beide Fassungen, erst node start.mjs, dann PORT=8080 NODE_ENV=production node start.mjs. Ihre Ausgaben stehen danach im Terminal untereinander. Die Werte vor dem Befehl gelten nur für diesen einen Aufruf, und beim nächsten sind sie wieder weg.

Warum jeder Wert Text ist

Die Umgebung kennt keine Datentypen. Sie reicht Text durch, und was du damit machst, ist deine Sache. PORT=8080 kommt als "8080" an, nicht als 8080.

Bei Zahlen fällt das schnell auf, weil man sowieso zu Number(...) greift. Bei Wahrheitswerten fällt es gar nicht auf. Und das ist die Falle.

Die Falle mit dem Wahrheitswert
const rohwert = process.env.DEBUG;

console.log("Rohwert:", rohwert);
console.log("Typ:", typeof rohwert);
console.log("Falsch geprüft:", rohwert ? "an" : "aus");
console.log("Richtig geprüft:", rohwert === "true" ? "an" : "aus");

DEBUG ist auf false gesetzt, und in der dritten Zeile steht trotzdem an.

Das liegt an JavaScript und nicht an Node. In einem if ist jeder Text wahr, außer dem leeren, und "false" ist ein Text mit fünf Zeichen.

Ich vergleiche Umgebungswerte deshalb immer ausdrücklich. Bei process.env.DEBUG === "true" ist klar, was gemeint ist. if (process.env.DEBUG) fragt nur, ob überhaupt etwas gesetzt ist, und das will man so gut wie nie wissen.

Die .env-Datei

Sechs Variablen vor jedem Befehl zu tippen hält niemand durch. Also kommen sie in eine Datei, eine Zeile je Wert, und Node liest sie beim Start ein:

node --env-file=.env start.mjs

Das ist seit Node 20.6 eingebaut, ein Paket brauchst du dafür nicht. Früher nahm man dafür dotenv, und in bestehenden Projekten wirst du es weiter finden.

Die .env gehört in die .gitignore, immer und ohne Ausnahme. In dieser Datei stehen Zugangsdaten, und in einem Repository haben die nichts verloren. Sie später wieder herauszunehmen reicht nicht. Was einmal committet war, also mit Git als Stand festgehalten, bleibt in der Historie stehen. Und wer an den Schlüssel will, sucht genau dort. Wie man damit umgeht, wenn es doch passiert ist, kommt in Abschnitt 15. Wie so eine .gitignore aussieht, steht in Lektion 5.4.

Ins Repository gehört stattdessen eine .env.example mit denselben Schlüsseln und leeren oder erfundenen Werten. Sie ist die Liste dessen, was gesetzt sein muss, und die darf jeder sehen.

Wo der Standardwert hingehört

Ein Standardwert steht an der Stelle, an der die Variable gelesen wird, und zwar genau einmal. Wenn process.env.PORT an vier Stellen in deinem Code auftaucht, hast du vier Gelegenheiten, den Standardwert unterschiedlich zu schreiben.

Üblich ist eine kleine Datei, die alle Werte einmal einliest, prüft und als fertiges Objekt weitergibt. Der restliche Code fragt dann dieses Objekt und nie mehr process.env. So eine Datei entsteht in Lektion 18.2. Fehlt dann eine Pflichtvariable, merkt dein Programm das gleich beim Start, während du noch davorsitzt, und nicht erst mitten in der Nacht bei der ersten Anfrage.

In der Aufgabe stehen zwei Zeilen, die Einstellungen aus der Umgebung lesen, und beide brauchen eine Reparatur.

Zum Mitnehmen

Aus der Umgebung kommt immer Text, und wer „false“ ungeprüft in ein if setzt, bekommt wahr. Der Standardwert steht dort, wo die Variable gelesen wird, und die .env gehört in die .gitignore.

Jetzt du

Basis Konto, kostenlos

Zu dieser Lektion gehört eine Aufgabe. Du schreibst den Code selbst, und nach jedem Lauf sagt dir eine Prüfliste, was schon stimmt.

Dafür brauchst du das Basis Konto. Es kostet nichts, und ein Passwort gibt es auch nicht.

In diesem Kurs läuft dein Code auf einem Server. Dafür hat das Basis Konto 1 Stunde im Monat, mehr Zeit gibt es mit dem Premium Konto.

Was in dieser Lektion steckt

  • Artikel mit 3 Beispielen zum Ausprobieren

    Steht hier, ohne Konto lesbar.

  • Aufgabe, dein Code läuft auf einem Server

    Öffnet sich mit dem Basis Konto.