Skip to content

Environment Variables

Jump to bottom
JinmuGo edited this page Jul 30, 2026 · 6 revisions

Environment Variables

환경 변수는 앱(@nestjs/config + zod) 이 직접 로드·검증하고, mise 는 환경별 .env 파일을 로드합니다.

역할 분리

담당 역할
앱 (@nestjs/config) .env 파일 로드 + zod 검증. 실행 방법(Docker, 프로덕션 등)과 무관하게 동작
mise 로컬 개발 인프라 설정(PGDATA 등)과 환경별 .env 파일 로드

포트

  • .env 파일의 PORT 값을 사용하며, 없으면 기본값 3000
  • 실제 값 파일은 gitignore 대상이므로 포트를 바꾸고 싶으면 환경별 .env 파일에서 변경

파일 구조

.env.development      # development 실제 값 (gitignore 대상)
.env.production       # production 실제 값 (gitignore 대상)
.env.example          # 변수 목록 (커밋, 신규 팀원은 복사해서 사용)
mise.toml             # development 환경 설정 (_.file = ".env.development")
mise.production.toml  # production 환경 설정 (_.file = ".env.production")
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
  1. 코드에서는 ConfigService로 타입 안전하게 접근
const config = app.get(ConfigService) as ConfigService<Env, true>
config.get('PORT', { infer: true }) // number

mise 환경별 실행

# development (default)
mise run start:dev

# production
mise --env=production run start:dev

mise는 환경에 맞는 .env 파일을 로드하고, 앱은 그 값을 zod로 검증합니다.

새 환경 변수 추가하기

  1. src/config/env.ts의 envSchema에 필드 추가
  2. .env.example에 변수 추가
  3. 필요하면 mise.toml / mise.production.toml에도 참조 추가
  4. 팀에 .env.development / .env.production 갱신 공유
// 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 서버 포트

Database

변수 기본값 설명
DB_HOST localhost PostgreSQL 호스트
DB_PORT 5432 PostgreSQL 포트
DB_USERNAME postgres PostgreSQL 사용자
DB_PASSWORD '' PostgreSQL 비밀번호
DB_DATABASE postgres PostgreSQL 데이터베이스 이름
DB_SSL false SSL 연결 사용 여부
DB_SSL_CA — SSL CA 인증서 (PEM 형식, DB_SSL=true일 때 사용)
DB_SYNCHRONIZE true TypeORM synchronize 활성화 여부. 원격 managed DB 사용 시 false 권장

OCI Object Storage (S3 compatible)

변수 기본값 설명
OCI_REGION ap-hyderabad-1 OCI Object Storage 리전
OCI_NAMESPACE — OCI Object Storage namespace (production 필수)
OCI_S3_ACCESS_KEY — S3 compatible access key (production 필수)
OCI_S3_SECRET_KEY — S3 compatible secret key (production 필수)
OCI_BUCKET_NAME_DEV momo-bucket-dev development 버킷 이름
OCI_BUCKET_NAME_PROD momo-bucket-prod production 버킷 이름
OCI_S3_ENDPOINT — S3 endpoint. 비어 있으면 https://<namespace>.compat.objectstorage.<region>.oraclecloud.com로 자동 조립

Production 필수 변수

NODE_ENV=production일 때 다음 변수는 비어 있으면 zod 검증에서 실패합니다.

  • DB_USERNAME
  • DB_PASSWORD
  • DB_DATABASE
  • OCI_NAMESPACE
  • OCI_S3_ACCESS_KEY
  • OCI_S3_SECRET_KEY
  • OCI_S3_ENDPOINT

Clone this wiki locally