Typowanie zmiennych środowiskowych
Nadaj process.env precyzyjny, zwalidowany typ
Typowanie zmiennych środowiskowych to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej TypeScript Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs TypeScript Academy zawiera 4 lekcji w sumie.
Problem z process.env
W Node process.env ma typ Record<string, string | undefined>. Każdej zmiennej może brakować, a wszystkie wartości są ciągami znaków, dlatego bezpośredni dostęp jest niebezpieczny i pozbawiony informacji o typach.
Deklarowanie interfejsu Env z typami
Najpierw należy dokładnie opisać konfigurację, której aplikacja faktycznie potrzebuje, używając prawidłowych typów oraz rozróżniając pola wymagane i opcjonalne.
interface Env {
PORT: number;
NODE_ENV: "development" | "production";
DATABASE_URL: string;
DEBUG?: boolean; // optional
}Odczytywanie surowych wartości
Wszystkie wartości są dostępne jako ciągi znaków lub undefined. Należy odczytywać je z zachowaniem ostrożności, ponieważ poszczególnych kluczy może po prostu nie być.
const rawPort = process.env.PORT; // string | undefined
const rawEnv = process.env.NODE_ENV; // string | undefinedZmienne wymagane a opcjonalne
Niektóre zmienne muszą istnieć, aby aplikacja mogła działać, podczas gdy inne mają rozsądne wartości domyślne. Funkcja pomocnicza dla wartości wymaganych zgłasza wyraźny błąd, gdy którejś z nich brakuje.
function required(name: string): string {
const v = process.env[name];
if (v === undefined) throw new Error("Missing env: " + name);
return v;
}Analizowanie liczb
Zmienne liczbowe wymagają konwersji i walidacji, ponieważ parseInt może zwrócić NaN. Należy opakować analizowanie w taki sposób, aby nieprawidłowe dane wejściowe były odrzucane natychmiast.
function num(name: string): number {
const n = Number(required(name));
if (Number.isNaN(n)) throw new Error(name + " is not a number");
return n;
}Analizowanie wartości logicznych
Wartości logiczne są przekazywane jako ciągi znaków, na przykład "true". Należy jawnie je normalizować, zamiast polegać na prawdziwości niepustego ciągu znaków.
function bool(name: string, def = false): boolean {
const v = process.env[name];
if (v === undefined) return def;
return v === "true" || v === "1";
}Tworzenie typowanej konfiguracji
Połącz przeanalizowane wartości w jeden obiekt zgodny z interfejsem Env. Od tego momentu reszta aplikacji korzysta z konfiguracji z określonymi typami i nigdy nie odwołuje się bezpośrednio do 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"),
};Ograniczanie unii ciągów znaków
W przypadku zmiennych, które mogą przyjmować wartości z ustalonego zbioru, należy sprawdzić wartość względem tego zbioru, aby nieoczekiwana wartość nie przeszła dalej jako wartość literałowa nieprawidłowego typu.
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;
}Centralizacja dostępu
Eksportuj pojedynczy obiekt env z jednego modułu. Każdy użytkownik importuje ten obiekt, zyskując pełną kontrolę typów i jedno miejsce do zmiany logiki analizowania.
export const config = env;
// elsewhere: import { config } from "./config";Rozszerzanie ProcessEnv (opcjonalne)
Można zadeklarować rozszerzenie modułu dla NodeJS.ProcessEnv, aby określić typ surowego dostępu, ale przeanalizowany obiekt konfiguracji jest bezpieczniejszy, ponieważ dodatkowo przeprowadza walidację i konwersję.
// declare global { namespace NodeJS { interface ProcessEnv { PORT: string } } }Dlaczego typowany obiekt konfiguracji jest lepszy
Przeanalizowana i zwalidowana konfiguracja zapewnia prawidłowe typy (liczby, wartości logiczne i unie), gwarantuje obecność wymaganych zmiennych oraz udostępnia jeden import dla całej aplikacji, zamiast rozproszonych, niebezpiecznych odczytów process.env.
Szybkie sprawdzenie
Szybkie sprawdzenie wiedzy z tej lekcji.
Podsumowanie
Zadeklaruj interfejs Env z typami, a następnie przeanalizuj process.env za pomocą funkcji pomocniczych, które konwertują i walidują wartości (liczby, wartości logiczne oraz unie ciągów znaków) i zgłaszają błąd w przypadku braku wymaganych zmiennych. Eksportuj jeden typowany obiekt config, aby aplikacja nigdy nie korzystała bezpośrednio z surowego process.env.
Często zadawane pytania
Czy lekcja „Typowanie zmiennych środowiskowych” jest bezpłatna?
Tak — pełny tekst „Typowanie zmiennych środowiskowych” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu TypeScript Academy, przejdź na CoddyKit PRO. Kurs TypeScript Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Typowanie zmiennych środowiskowych”?
Nadaj process.env precyzyjny, zwalidowany typ Ćwiczysz TypeScript Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć TypeScript Academy?
Nie wymagamy żadnego doświadczenia. TypeScript Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.
Ile czasu zajmuje lekcja „Typowanie zmiennych środowiskowych”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji TypeScript Academy?
Tak. Każda lekcja TypeScript Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Typowanie zmiennych środowiskowych
- Konfiguracja walidowana schematem
- Warstwowanie konfiguracji i wartości domyślne
- Sekrety i bezpieczeństwo typów