← Все статьи

Валидация переменных окружения в TypeScript

Схема для .env, проверка в CI и автогенерация типов — как поймать PORT=abc и пустой API_KEY до деплоя.

Теги
BackendНовостиNode.js
Содержание

Коротко

Опечатка в .env часто всплывает только в проде: PORT=abc, NODE_ENV=staging на боевом сервере, пустой API_KEY. На Dev.to показывают схему валидации и CLI env-haven — проверка до старта приложения и в CI.

Что произошло

Автор описывает типичные сбои: строка вместо числа порта, неверный префикс в DATABASE_URL, отсутствующие обязательные ключи. TypeScript не спасает — process.env остаётся string | undefined.

Решение — JSON-схема переменных: тип, required, enum, форматы (url, port, email), значения по умолчанию. Файл checkmyenv.config.json в репозитории становится единым источником правды.

Инструмент env-haven (MIT, без зависимостей) валидирует .env, возвращает exit code 1 при ошибках и умеет генерировать .env.example и env.d.ts.

Почему это важно

Конфиг через окружение — стандарт для Node/Docker/Kubernetes, но без контракта команда полагается на память и копипаст. Один неверный NODE_ENV может подмешать staging-ключи в production-трафик.

Проблема Без схемы Со схемой
PORT=abc Падение при bind Ошибка в CI
NODE_ENV=staging в проде Неверные флаги и ключи enum отклонит значение
Пустой API_KEY 401 от API «внезапно» «Missing required variable» до деплоя

Схема + CI дешевле, чем ночной инцидент и разбор логов.

На практике

  1. Опишите переменные в checkmyenv.config.json (тип, required, format, default).
  2. В PR добавьте шаг npx env-haven — тот же .env.example, что видит новый разработчик.
  3. Запускайте env-haven generate при изменении схемы и коммитьте обновлённый .env.example.
  4. env-haven types — интерфейс Env для обёртки над process.env после успешной проверки.
  5. Альтернатива в коде: Zod / Valibot при старте процесса — тот же принцип, если CLI не нужен.

Для нескольких сред копируйте нужный .env перед проверкой в pipeline или держите отдельные схемы/профили.

Итог

Валидация env — маленький шаг с большим эффектом: первый же прогон ловит опечатки, которые иначе доезжают до мониторинга. Имеет смысл завести схему в любом TypeScript-бэкенде, где конфиг живёт в .env.