process.env w Node.js: odczyt zmiennych środowiskowych

process.env to obiekt z jedną właściwością na każdą zmienną środowiskową, którą powłoka przekazała twojemu programowi Node.js: process.env.PORT, process.env.DATABASE_URL i tak dalej. Zmienna, której nie ustawiono, ma wartość undefined, a ustawiona zmienna to zawsze string. Odczytaj ją raz przy starcie, daj jej wartość domyślną i zamień na typ, którego potrzebujesz.

// 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);

Wypisało shop on port 8080 in eu-west (REGION nigdy nie ustawiono, więc zadziałała wartość domyślna), a potem string number: zmienna jest tekstem, dopóki Number() jej nie zamieni. Usuń dwa pierwsze przypisania i uruchom ponownie, żeby zobaczyć wszystkie wartości domyślne.

Ustawianie zmiennych środowiskowych w powłoce

Zmienne pochodzą z miejsca, w którym uruchamiasz Node.js. W terminalu:

// 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

Platformy hostingowe (Heroku, Render, Vercel, Docker, Kubernetes) mają do tego stronę ustawień albo plik; twój kod czyta je tak samo.

Wszystko jest stringiem

Stąd bierze się większość błędów z process.env. 'false' i '0' to niepuste stringi, więc są 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');

Naiwne sprawdzenie wypisało debug is ON dla zmiennej ustawionej na false, więc porównuj z dokładnie takim stringiem, jakiego oczekujesz. Przy liczbach Number(process.env.X) zamienia brakującą wartość w NaN, więc ustaw wartość domyślną przed zamianą, jak w pierwszym przykładzie z ??.

NODE_ENV

NODE_ENV to konwencja, a nie funkcja Node.js: Node.js nigdy go nie ustawia. Czytają go biblioteki. Express na przykład ukrywa stack trace na stronach błędów, gdy ma wartość production, a wiele narzędzi pomija sprawdzenia przeznaczone tylko do developmentu.

// 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);

Wypisało mode: production i verbose logs: false; zmień 'production' na 'development', a druga linia się odwróci. Trzymaj się production, development i test, bo biblioteki sprawdzają dokładnie te słowa.

Pliki .env: --env-file i dotenv

Wpisywanie każdej zmiennej przed node szybko się nudzi. Plik .env trzyma je w folderze projektu, po jednej na linię:

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

Node.js 20.6 i nowsze czytają go przez flagę, bez żadnego pakietu:

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

W starszych wersjach, albo jeśli wolisz, zainstaluj pakiet dotenv (npm install dotenv) i wczytaj go na samej górze pliku startowego, zanim jakikolwiek kod odczyta process.env:

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

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

Żadne z nich nie nadpisuje zmiennej, która jest już ustawiona w powłoce, więc ustawienia produkcyjne wygrywają z plikiem.

Szybki błąd przy brakujących zmiennych

Brakujący adres bazy danych powinien zatrzymać program przy starcie z jasnym komunikatem, a nie wywrócić go godzinę później przy pierwszym żądaniu:

// 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');
}

Wypisało Missing environment variables: API_KEY; dodaj na górze process.env.API_KEY = 'test';, a wypisze się Config OK. W prawdziwym programie po komunikacie wywołaj process.exit(1), bo niezerowy kod wyjścia to sygnał dla skryptu wdrożeniowego albo platformy kontenerowej, że start się nie udał.

Nigdy nie commituj sekretów

Dodaj .env do .gitignore tego samego dnia, w którym go tworzysz. Zamiast niego commituj .env.example z nazwami zmiennych i fałszywymi wartościami, żeby inni wiedzieli, co ustawić. Klucz, który kiedykolwiek trafił do repozytorium, traktuj jako wykradziony i wymień go, nawet jeśli później usuniesz commit.