re:re:actable
Урок 033 минуты чтения

Переменные окружения, .env и безопасное хранение секретов

На этой странице
Кратко

Переменные окружения хранят настройки, которые зависят от среды: порт, режим запуска, URL базы данных, токены и секреты. В Node.js они доступны через process.env, а .env-файлы помогают задавать их локально.

Секреты не должны лежать в коде и репозитории. Их обычно передают через переменные окружения, secret manager, настройки платформы деплоя или защищенные CI/CD-переменные.

Вопрос

Как работать с переменными окружения и .env в Node.js и как безопасно хранить секреты?

process.env

const port = process.env.PORT || 3000;
const mode = process.env.NODE_ENV || 'development';
 
console.log({ port, mode });

Все значения в process.env являются строками или undefined.

const timeout = Number(process.env.TIMEOUT_MS || 5000);

Что хранить в env?

ЗначениеПример
ПортPORT=3000
РежимNODE_ENV=production
URL базыDATABASE_URL=postgres://...
СекретыJWT_SECRET=...
API-ключиSTRIPE_SECRET_KEY=...

.env-файл

PORT=3000
NODE_ENV=development
API_URL=https://api.example.com

В современных версиях Node.js есть встроенная поддержка env-файлов через CLI-флаг.

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

Во многих проектах также встречается пакет dotenv.

Валидация env

Не стоит разбросанно читать env по всему проекту. Лучше собрать конфиг в одном месте и проверить обязательные значения.

const required = ['DATABASE_URL', 'JWT_SECRET'];
 
for (const name of required) {
  if (!process.env[name]) {
    throw new Error(`Missing environment variable: ${name}`);
  }
}

Что считается секретом?

Секреты - это данные, которые дают доступ к системе или деньгам:

  • токены API;
  • пароли;
  • JWT secret;
  • приватные ключи;
  • строки подключения к базе;
  • webhook signing secret.

Плохо: секрет в коде

const stripeKey = 'sk_live_123456';

Такой ключ может попасть в GitHub, логи, скриншоты и историю коммитов.

Хорошо: секрет из окружения

const stripeKey = process.env.STRIPE_SECRET_KEY;
 
if (!stripeKey) {
  throw new Error('Missing STRIPE_SECRET_KEY');
}

Локально значение можно положить в .env, а на сервере - в настройки окружения.

.gitignore и .env.example

.env
.env.*
!.env.example

Файл .env.example можно коммитить, если в нем только имена переменных без реальных значений.

PORT=3000
DATABASE_URL=
JWT_SECRET=

Что важно помнить

  • node --env-file=.env app.js загружает файл без пакета dotenv; process.loadEnvFile() делает то же из кода.
  • Все значения process.env — строки: приводите типы и валидируйте схемой при старте.
  • Коммитят только .env.example без значений; .env — в .gitignore.
  • Утекший секрет перевыпускают: удаление из кода не убирает его из истории git.

Мини-шпаргалка

  • process.env хранит переменные окружения.
  • Значения env - строки.
  • .env удобен для локальной разработки.
  • Секреты нельзя коммитить в репозиторий.
  • Обязательные env лучше валидировать при старте приложения.
  • Секреты не хранят в коде.
  • .env нельзя коммитить.
  • .env.example можно использовать как шаблон.
  • При старте проверяй обязательные секреты.
  • Если секрет утек, его нужно перевыпустить, а не просто удалить из кода.

Документация

Node.js: process.env, Node.js: --env-file, The Twelve-Factor App: Config.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам