process.env в Node.js: переменные окружения

process.env это объект, в котором по одному свойству на каждую переменную окружения, переданную оболочкой вашей программе на Node.js: process.env.PORT, process.env.DATABASE_URL и так далее. Переменная, которую не задали, читается как undefined, а заданная всегда строка. Прочитайте её один раз при запуске, задайте значение по умолчанию и преобразуйте в нужный тип.

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

Программа вывела shop on port 8080 in eu-west (REGION никто не задавал, поэтому сработало значение по умолчанию), а затем string number: переменная остаётся текстом, пока её не преобразует Number(). Удалите первые два присваивания и запустите снова, чтобы увидеть все значения по умолчанию.

Как задать переменные окружения в терминале

Переменные приходят оттуда, откуда запускают Node.js. В терминале:

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

У хостингов (Heroku, Render, Vercel, Docker, Kubernetes) для этого есть страница настроек или файл, а код читает переменные точно так же.

Всё это строки

Отсюда берётся большинство ошибок с process.env. 'false' и '0' это непустые строки, поэтому они 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');

Наивная проверка вывела debug is ON для переменной со значением false, поэтому сравнивайте с точной строкой, которую ожидаете. С числами Number(process.env.X) превращает отсутствующее значение в NaN, так что подставляйте значение по умолчанию до преобразования, как в первом примере с ??.

NODE_ENV

NODE_ENV это соглашение, а не возможность Node.js: сам Node.js его никогда не задаёт. Его читают библиотеки. Express, например, убирает stack trace со страниц ошибок, когда там production, а многие инструменты пропускают проверки, нужные только при разработке.

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

Программа вывела mode: production и verbose logs: false; замените 'production' на 'development', и вторая строка поменяется. Используйте production, development и test, потому что библиотеки проверяют именно эти слова.

Файлы .env: --env-file и dotenv

Набирать каждую переменную перед node быстро надоедает. Файл .env хранит их в папке проекта, по одной на строку:

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

Node.js 20.6 и новее читает его по флагу, без всяких пакетов:

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

В старых версиях, или если так удобнее, установите пакет dotenv (npm install dotenv) и загрузите его в самом начале входного файла, до любого кода, который читает process.env:

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

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

Ни один из способов не перезаписывает переменную, которая уже задана в оболочке, поэтому настройки продакшена важнее файла.

Падайте сразу, если переменной нет

Если нет адреса базы данных, программа должна остановиться при запуске с понятным сообщением, а не упасть через час на первом запросе:

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

Программа вывела Missing environment variables: API_KEY; добавьте в начало process.env.API_KEY = 'test';, и она выведет Config OK. В настоящей программе после сообщения вызовите process.exit(1): по ненулевому коду выхода скрипт деплоя или контейнерная платформа понимает, что запуск не удался.

Никогда не коммитьте секреты

Добавьте .env в .gitignore в тот же день, когда создали его. Вместо него закоммитьте .env.example с именами переменных и ненастоящими значениями, чтобы остальные знали, что задать. Ключ, который хоть раз попал в репозиторий, считайте утёкшим и замените, даже если потом удалите коммит.