Переменные окружения, .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.