Config-модуль: типизированный, валидируемый env

ConfigModule оборачивает dotenv и централизует чтения

@nestjs/config — тонкий, мнениевый слой поверх dotenv (библиотека, которая читает .env-файл и подкладывает переменные в process.env). Ты регистрируешь его один раз через ConfigModule.forRoot(); он читает .env (и .env.${NODE_ENV}, если указать на него), подмешивает process.env, опционально валидирует результат и отдаёт всё через инжектируемый ConfigService. Пометка isGlobal: true означает, что любой feature-модуль может инжектить ConfigService без повторного импорта ConfigModule, а cache: true мемоизирует чтения, чтобы config.get() не перечитывал process.env при каждом вызове.

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,                              // инжектить ConfigService где угодно, без реимпорта
      cache: true,                                 // мемоизировать чтения process.env
      envFilePath: `.env.${process.env.NODE_ENV}`, // файл на окружение
      expandVariables: true,                       // интерполяция ${HOST}:${PORT} в .env
      ignoreEnvFile: process.env.NODE_ENV === 'production', // прод: только реальный env, без файла
    }),
  ],
})
export class AppModule {}

Дальше ты читаешь значения типизированным геттером — config.get<string>('DATABASE_URL') — вместо обращения к process.env напрямую. Выигрыш не в синтаксисе; он в том, что ConfigService — настоящий provider. Он инжектируемый, поэтому участвует в DI; он мокается, поэтому тесты могут передать фейковую конфигурацию вместо мутации глобального process.env; и поскольку чтения централизованы, валидация происходит ровно в одном месте.

В проде ставь ignoreEnvFile: true. Закоммиченный .env никогда не должен быть источником истины в проде — значения приходят из реального окружения (оркестратора, secrets-менеджера, платформы), а чтение устаревшего файла — это как раз способ протащить staging-креды в прод-деплой.

Сеньорская мысль: валидируй на старте, fail fast

Спроси себя: когда должен упасть неправильно сконфигурированный деплой — на старте, где инженер увидит это в логе деплоя, или через три часа, когда клиент попадёт на сломанный путь кода? Ответ определяет всё, что идёт дальше.

Определяющая фича ConfigModule — не загрузка, а валидация. Передай validationSchema (Joi — библиотека декларативной валидации объектов), и Nest валидирует слитое окружение один раз, на init модуля. Если обязательная переменная отсутствует или сломана, процесс выбрасывает на bootstrap с точным сообщением и вообще не стартует. Это превращает скрытый undefined времени запроса в громкий, немедленный сбой времени деплоя.

import * as Joi from 'joi';

ConfigModule.forRoot({
  isGlobal: true,
  validationSchema: Joi.object({
    NODE_ENV: Joi.string().valid('development', 'test', 'production').default('development'),
    PORT: Joi.number().port().default(3000),
    DATABASE_URL: Joi.string().uri().required(),   // нет -> старт падает
    STRIPE_SECRET_KEY: Joi.string().required(),    // баг из хука, пойманный на старте
  }),
  validationOptions: { abortEarly: false },        // сообщить про ВСЕ плохие переменные, не только первую
});

Предпочитаешь Zod или кастомную validate-функцию, если не хочешь тащить Joi — Nest принимает любую validate: (config) => validatedConfig, которая выбрасывает при провале. Она выполняется в той же точке lifecycle и даёт ту же гарантию fail-fast:

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),                  // выбросит на старте, если нет / сломано
});

ConfigModule.forRoot({
  isGlobal: true,
  validate: (raw) => envSchema.parse(raw),         // ZodError -> процесс отказывается стартовать
});

В любом случае контракт один: сломанный DATABASE_URL роняет старт с понятным сообщением, а не молча остаётся undefined до первого запроса в проде.

Namespace-конфиг через registerAs и типизированная инъекция

Плоский мешок строк config.get('DATABASE_HOST') не масштабируется — ключи stringly-typed, а группировка неявная. registerAs('database', factory) определяет namespace: именованный объект конфигурации, собранный из process.env, зарегистрированный через forFeature или массив load и — главное — инжектируемый как строго типизированная единица.

// database.config.ts
import { registerAs } from '@nestjs/config';

export default registerAs('database', () => ({
  host: process.env.DATABASE_HOST ?? 'localhost',
  port: parseInt(process.env.DATABASE_PORT ?? '5432', 10),
  url: process.env.DATABASE_URL,
}));

// любой provider
import { Inject, Injectable } from '@nestjs/common';
import { ConfigType } from '@nestjs/config';
import databaseConfig from './database.config';

@Injectable()
export class DbService {
  constructor(
    @Inject(databaseConfig.KEY)
    private readonly dbConfig: ConfigType<typeof databaseConfig>,
  ) {}

  connect() {
    // dbConfig.port типизирован как `number`, dbConfig.host — `string` — без кастов, автокомплит работает
    return `${this.dbConfig.host}:${this.dbConfig.port}`;
  }
}

ConfigType<typeof databaseConfig> выводит статический тип прямо из возвращаемого значения фабрики, а databaseConfig.KEY — это DI-токен для этого namespace. В итоге конфиг типизирован (компилятор знает, что port — number), валидирован (namespace собран из env, прошедшего схему) и тестируем (инжектишь заглушку для databaseConfig.KEY в юнит-тесте). Сравни с process.env.DATABASE_PORT, размазанным по кодовой базе: нетипизировано (всегда string | undefined), невалидировано, нетестируемо и невидимо для DI.

process.env vs ConfigService vs самописный синглтон

Почему просто не читать process.env или не собрать один объект config.ts самому? Таблица делает разрыв конкретным:

Самописный синглтон даёт типы и одно место чтения, но это состояние уровня модуля, которое нельзя инжектить или чисто мокать, а валидация — это та дисциплина, которую ты не забыл написать. ConfigService даёт все три — типы, валидацию на старте и DI — бесплатно.