TypeScript Academy · Lektion

Umgebungsvariablen typisieren

Geben Sie process.env einen präzisen, validierten Typ.

Umgebungsvariablen typisieren ist eine kostenlose TypeScript Academy-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des TypeScript Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der TypeScript Academy-Kurs umfasst insgesamt 4 Lektionen.

Das Problem mit process.env

In Node ist process.env als Record<string, string | undefined> typisiert. Jede Variable könnte fehlen, und alle Werte sind Strings. Der direkte Zugriff ist daher unsicher und nicht typsicher.

Eine typisierte Env-Schnittstelle deklarieren

Beschreiben Sie zunächst die Konfiguration, die Ihre Anwendung tatsächlich benötigt, als präzise Schnittstelle mit den richtigen Typen sowie mit Pflicht- und optionalen Feldern.

interface Env {
  PORT: number;
  NODE_ENV: "development" | "production";
  DATABASE_URL: string;
  DEBUG?: boolean; // optional
}

Rohwerte lesen

Alle Werte kommen als Strings oder undefined an. Sie müssen sie defensiv lesen, da die Schlüssel schlicht nicht vorhanden sein können.

const rawPort = process.env.PORT; // string | undefined
const rawEnv = process.env.NODE_ENV; // string | undefined

Erforderliche und optionale Variablen

Einige Variablen müssen vorhanden sein, damit die Anwendung ausgeführt werden kann; andere haben sinnvolle Standardwerte. Ein Helper für erforderliche Werte bricht mit einer deutlichen Fehlermeldung ab, wenn ein Wert fehlt.

function required(name: string): string {
  const v = process.env[name];
  if (v === undefined) throw new Error("Missing env: " + name);
  return v;
}

Zahlen parsen

Numerische Variablen müssen umgewandelt und validiert werden, da parseInt NaN liefern kann. Kapseln Sie das Parsen, damit ungültige Eingaben sofort abgelehnt werden.

function num(name: string): number {
  const n = Number(required(name));
  if (Number.isNaN(n)) throw new Error(name + " is not a number");
  return n;
}

Boolesche Werte parsen

Boolesche Werte kommen als Strings wie "true" an. Normalisieren Sie sie ausdrücklich, statt sich auf den Wahrheitswert eines nicht leeren Strings zu verlassen.

function bool(name: string, def = false): boolean {
  const v = process.env[name];
  if (v === undefined) return def;
  return v === "true" || v === "1";
}

Die typisierte Konfiguration erstellen

Fügen Sie die geparsten Werte zu einem Objekt zusammen, das der Env-Schnittstelle entspricht. Von nun an verwendet der restliche Anwendungscode die typisierte Konfiguration und niemals direkt process.env.

const env: Env = {
  PORT: num("PORT"),
  NODE_ENV: required("NODE_ENV") as Env["NODE_ENV"],
  DATABASE_URL: required("DATABASE_URL"),
  DEBUG: bool("DEBUG"),
};

String-Union-Typen einschränken

Bei Variablen mit einer festen Wertemenge sollten Sie gegen diese Menge validieren, damit sich kein unerwarteter Wert als falscher Literaltyp einschleichen kann.

function oneOf<T extends string>(name: string, allowed: readonly T[]): T {
  const v = required(name) as T;
  if (!allowed.includes(v)) throw new Error(name + " invalid");
  return v;
}

Zugriff zentralisieren

Exportieren Sie das einzige env-Objekt aus einem Modul. Jeder Verwender importiert es und erhält dadurch vollständige Typisierung sowie eine zentrale Stelle zum Ändern der Parsing-Logik.

export const config = env;
// elsewhere: import { config } from "./config";

ProcessEnv erweitern (optional)

Sie können eine Modulaugmentation für NodeJS.ProcessEnv deklarieren, um den direkten Zugriff zu typisieren. Ein geparstes Konfigurationsobjekt ist jedoch sicherer, weil es zusätzlich validiert und umwandelt.

// declare global { namespace NodeJS { interface ProcessEnv { PORT: string } } }

Warum ein typisiertes Konfigurationsobjekt überlegen ist

Eine geparste und validierte Konfiguration liefert die richtigen Typen (Zahlen, boolesche Werte, Union-Typen), garantiert das Vorhandensein erforderlicher Variablen und bietet einen einzigen Import für die gesamte Anwendung – statt verstreuter unsicherer Zugriffe auf process.env.

Kurzer Test

Kurzer Test zu dieser Lektion.

Zusammenfassung

Deklarieren Sie eine typisierte Env-Schnittstelle und parsen Sie anschließend process.env mit Helpern, die Werte umwandeln und validieren (Zahlen, boolesche Werte, String-Union-Typen) und bei fehlenden erforderlichen Variablen abbrechen. Exportieren Sie ein einziges typisiertes config-Objekt, damit die Anwendung niemals auf das rohe process.env zugreift.

Häufig gestellte Fragen

Ist die Lektion „Umgebungsvariablen typisieren“ kostenlos?

Ja — der vollständige Text von „Umgebungsvariablen typisieren“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des TypeScript Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der TypeScript Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Umgebungsvariablen typisieren“?

Geben Sie process.env einen präzisen, validierten Typ. Du übst TypeScript Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um TypeScript Academy zu starten?

Keine Vorkenntnisse erforderlich. TypeScript Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.

Wie lange dauert die Lektion „Umgebungsvariablen typisieren“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser TypeScript Academy-Lektion Code schreiben und ausführen?

Ja. Jede TypeScript Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

Umgebungsvariablen typisieren
Schema-validierte Konfiguration
Konfigurationsschichten und Standardwerte
Secrets und Typsicherheit

← Zurück zu TypeScript Academy