NestJS Configuration — 환경 변수와 설정을 관리하는 방법

애플리케이션을 개발할 때 데이터베이스 접속 정보, API 키, 포트 번호처럼 환경마다 달라지는 값을 코드에 하드코딩하면 보안 문제와 유지보수 비용이 동시에 발생한다. NestJS는 @nestjs/config 패키지를 통해 .env 파일과 환경 변수를 모듈 시스템에 자연스럽게 통합한다. 이 패키지 하나로 타입 안전한 설정 주입과 환경별 분리를 모두 해결할 수 있다.

설치와 기본 설정

npm install @nestjs/config

루트 모듈에서 ConfigModule.forRoot 를 한 번 등록하면 애플리케이션 전체에서 설정값을 읽을 수 있다.

// app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,   // 다른 모듈에서 import 없이 사용
      envFilePath: '.env',
    }),
  ],
})
export class AppModule {}

isGlobal: true — 한 번 등록한 ConfigModule을 모든 하위 모듈에서 별도 import 없이 사용할 수 있게 만드는 옵션.

ConfigService로 값 읽기

ConfigService를 생성자에 주입하면 get 메서드로 환경 변수를 읽는다.

// app.service.ts
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class AppService {
  constructor(private readonly config: ConfigService) {}

  getDatabaseUrl(): string {
    return this.config.get<string>('DATABASE_URL');
  }

  getPort(): number {
    return this.config.get<number>('PORT', 3000); // 기본값 지정 가능
  }
}

get<T>(key, defaultValue?) — 제네릭으로 반환 타입을 명시하면 TypeScript 타입 추론이 동작한다.

환경별 설정 분리

.env ← 공통 기본값 (git 추적 제외) .env.development ← 개발 환경 .env.production ← 운영 환경

envFilePath에 배열을 넘기면 앞쪽 파일이 우선순위를 가진다.

ConfigModule.forRoot({
  isGlobal: true,
  envFilePath: [`.env.${process.env.NODE_ENV}`, '.env'],
})

네임스페이스 설정 팩토리

프로젝트가 커지면 설정 키가 충돌할 수 있다. 설정 팩토리 함수로 네임스페이스를 분리하면 관리가 쉬워진다.

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

export default registerAs('database', () => ({
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT, 10) || 5432,
  name: process.env.DB_NAME,
}));

// app.module.ts
import databaseConfig from './config/database.config';

ConfigModule.forRoot({
  isGlobal: true,
  load: [databaseConfig],
})

// 사용처
const host = this.config.get<string>('database.host');

registerAs — 설정 객체에 네임스페이스 접두사를 붙여 등록하는 헬퍼. 점 표기법(database.host)으로 중첩 키에 접근한다.

구조 한눈에 보기

.env 파일
    |
    v
ConfigModule.forRoot()   <-- AppModule에 1회 등록
    |
    v
ConfigService (DI 컨테이너)
    |
    +-- get('KEY')           단순 키-값
    +-- get('ns.key')        네임스페이스 팩토리
    +-- get<T>('KEY', def)   타입 + 기본값

주요 옵션 비교

ignoreEnvFile: true 는 운영 환경에서 .env 파일 없이 컨테이너 환경 변수만 사용할 때 유용하다. CI/CD 파이프라인에서 시크릿을 주입하는 패턴과 잘 맞는다.