NestJS 마스터 시리즈 7화. ConfigModule과 환경 설정 – .env 관리와 설정 계층 구조의 원칙

"설정은 분산되고 계층화되어야 한다. 관리되지 않는 설정은 기술 부채다"

NestJS에서 ConfigModule을 활용한 환경 설정 관리 방법을 설명합니다. .env 파일 사용, 설정 계층 설계, 타입 안전성 확보, 환경별 분리 전략까지 실무 중심으로 구성합니다.

---

설정은 코드다 – 환경 설정을 코드로 관리하자

많은 Node.js 프로젝트들이 .env만 두고 끝낸다. 하지만 규모가 커지면 설정의 계층화, 타입 안전성, 환경별 분리 없이는 유지보수가 어려워진다.

NestJS는 @nestjs/config 모듈을 통해 설정을 코드 수준에서 관리할 수 있도록 지원한다.
이 방식은 다음과 같은 이점을 제공한다:

• 설정 접근 방식의 일관성 유지
• 환경 변수 누락, 오타 방지
• 테스트 환경 분리와 유연한 설정 오버라이딩

---

설치 및 기본 설정

npm install @nestjs/config

AppModule에 ConfigModule을 등록한다.

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

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // 전역 설정
      envFilePath: ['.env.development', '.env'], // 우선순위 지정
    }),
  ],
})
export class AppModule {}

.env 예시:

PORT=3000
DB_HOST=localhost
DB_PORT=5432

---

설정 값 사용하기

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class UsersService {
  constructor(private configService: ConfigService) {}

  getDatabaseHost(): string {
    return this.configService.get<string>('DB_HOST');
  }
}

• ConfigService는 DI로 주입받는다.
• get() 메서드를 통해 환경 변수를 타입 안전하게 조회할 수 있다.

---

고급 전략 – 커스텀 설정 모듈 만들기

단순 문자열 조회를 넘어서, 설정을 기능별로 모듈화할 수 있다.

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

ConfigModule 등록 시 사용:

ConfigModule.forRoot({
  load: [configuration], // 커스텀 설정 함수
})

사용 예시:

const dbHost = this.configService.get<string>('database.host');

---

환경별 설정 파일 분리 전략

환경 파일명 설명

개발	.env.development	로컬 개발 환경
운영	.env.production	실제 배포 환경
테스트	.env.test	테스트 환경 전용 변수

실행 시 환경에 따라 다르게 불러오도록 NODE_ENV에 따라 파일명을 지정한다.

---

설정 검증 – Joi를 이용한 타입 안전성 확보

설정 누락이나 잘못된 값 입력을 방지하려면 검증 로직을 추가해야 한다.

import * as Joi from 'joi';

ConfigModule.forRoot({
  validationSchema: Joi.object({
    PORT: Joi.number().default(3000),
    DB_HOST: Joi.string().required(),
    DB_PORT: Joi.number().required(),
  }),
})

• 실행 시점에 .env 파일을 검사하고, 유효하지 않으면 애플리케이션 구동 중단

---

마무리 인사이트

설정은 개발 속도와 서비스 안정성 모두에 영향을 준다.
NestJS의 ConfigModule은 단순한 환경 변수 사용을 넘어, 설계 가능한 설정 시스템을 가능하게 한다.

• 설정은 반드시 코드로 관리하라
• 설정 값은 타입 검증과 계층화를 통해 체계적으로 다뤄야 한다
• 환경별로 명확히 분리하고, 검증은 실행 시점에 수행하라

설정을 코드로 관리할 수 없다면, 설정이 프로젝트를 망가뜨릴 수 있다

---

다음 회차 예고

8화. 비동기 프로그래밍과 RxJS – NestJS의 Reactive 구조를 이해하라
Promise와 Observable의 차이, RxJS 기반의 비동기 처리 전략을 실무 예제로 설명합니다.