Environment Variables

Environment Variables

환경 변수는 앱(@nestjs/config + zod) 이 직접 로드·검증하고, mise 는 로컬 개발 인프라 설정만 담당합니다.

역할 분리

담당	역할
앱 (@nestjs/config)	.env 로드 + zod 검증. 실행 방법(Docker, 프로덕션 등)과 무관하게 동작
mise	로컬 개발 인프라 설정(PGDATA 등)과 앱 밖 CLI 스크립트용 env 로드

포트

• .env의 PORT 값을 사용하며, 없으면 기본값 3000
• .env는 gitignore 대상이므로 포트를 바꾸고 싶으면 각자 로컬 .env에서 변경

파일 구조

.env                  # 실제 값 (gitignore 대상)
.env.example          # 변수 목록 (커밋, 신규 팀원은 복사해서 사용)
src/config/env.ts     # zod 스키마 + validateEnv 함수

동작 방식

1. 부팅 시 ConfigModule.forRoot({ validate: validateEnv })가 .env + process.env를 zod 스키마로 검증
2. 검증 실패 시 명확한 에러와 함께 부팅 중단 (fail-fast)

Error: Invalid environment variables:
- PORT: Invalid input: expected number, received NaN

3. 코드에서는 ConfigService로 타입 안전하게 접근

const config = app.get(ConfigService) as ConfigService<Env, true>
config.get('PORT', { infer: true }) // number

새 환경 변수 추가하기

1. src/config/env.ts의 envSchema에 필드 추가
2. .env.example에 변수 추가
3. 팀에 .env 갱신 공유

// src/config/env.ts
const envSchema = z.object({
  // ...
  // biome-ignore lint/style/useNamingConvention: 환경 변수 이름과 동일하게 유지
  DB_HOST: z.string().default('localhost'),
})

스키마 키는 환경 변수 이름(CONSTANT_CASE)을 그대로 쓰므로 biome 네이밍 규칙 예외 주석(biome-ignore)을 붙입니다.

현재 변수 목록

변수	기본값	설명
NODE_ENV	development	development / test / production
PORT	3000	서버 포트