Переменные окружения

Что такое переменные окружения

Переменная окружения это имя и текстовое значение, например PORT=3000, существующие в процессе, в котором работает приложение. Метод twelve-factor app определяет конфигурацию как всё, что может меняться между развёртываниями, например адреса баз данных и учётные данные, и требует строго отделять её от кода. Его проверка такова: можно ли в любой момент открыть исходный код, не раскрыв ни одной учётной записи.

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

const port = Number(process.env.PORT) || 3000;
const dbHost = process.env.DB_HOST;

Тот же код работает на вашем ноутбуке и на VPS с разными настройками, и менять исходники для переключения не нужно.

Файл .env и .gitignore

Вводить переменные в терминале при каждом запуске утомительно, поэтому инструменты читают их из файла .env со строками вида ИМЯ=значение. Новые версии Node.js умеют загружать такой файл командой node --env-file=.env app.js. Файл с выдуманными значениями выглядит так:

PORT=3000
DB_HOST=localhost
DB_PASSWORD=fake-password-change-me
API_KEY=fake_key_0000

Настоящий файл никогда не должен попасть в git. Добавьте эти строки в .gitignore и закоммитьте копию .env.example со значениями-заглушками, чтобы остальные знали, какие имена задавать:

.env
.env.*
!.env.example

Предупреждение из документации Git: файлы, которые Git уже отслеживает, на .gitignore не реагируют. Если .env однажды закоммитили, выполните git rm --cached .env, а затем считайте все значения в нём утёкшими и ротируйте их. См. что делать после утечки API-ключа.

Переменные фронтенда публичны

Новички часто думают, что всё из .env скрыто. Фреймворки, собирающие код для браузера, работают иначе. В документации Vite сказано, что переменные с префиксом VITE_ попадают в клиентский код после сборки и не должны содержать чувствительные данные вроде API-ключей. В Next.js переменные с префиксом NEXT_PUBLIC_ при сборке встраиваются в JavaScript, отправляемый в браузер, а остальные остаются в серверном окружении.

Правило простое: если значение нужно браузеру, это не секрет. Публичный ключ базы данных допустим, только если доступ защищён правилами вроде защиты на уровне строк. Всё, что тратит деньги или читает все данные, должно жить в серверном коде за вашим собственным API. Проверьте это перед запуском по чек-листу безопасности для вайб-кодинга, а заодно поищите значение ключа через grep в папке готовой сборки, обычно dist или build.

Где переменные окружения утекают

Переменные окружения удобны, но не приватны. В памятке OWASP по управлению секретами сказано, что они, как правило, доступны всем процессам и могут попасть в логи или дампы системы, а использовать их советуют, только если нет других способов.

• Логи и страницы ошибок. Никогда не выводите process.env или всё окружение при отладке.
• Образы и репозитории. Не зашивайте значения в строки Docker ENV или ARG и не коммитьте их в git.
• Открытые файлы. Файл .env, который отдаёт веб-сервер, раскрывает всё; см. открытые файлы .env и .git.
• Широкий доступ. Держите файл с правами 600 и запускайте приложение от непривилегированного пользователя.

Для ценных учётных данных переходите на смонтированные файлы секретов или менеджер секретов, как описано в статье об управлении секретами.

Связанные термины: Управление секретами, Наименьшие привилегии, VPS, Вайб-кодинг, Защита на уровне строк (RLS).