Next.js 환경변수 검증 체크리스트

환경변수 문제는 항상 단순하게 시작합니다. 키 하나 오타, 값 하나 누락, 타입 하나 불일치. 그런데 배포 후에는 "특정 기능에서만 간헐적으로 실패" 같은 형태로 나타나서 원인 찾는 시간이 길어집니다. 이건 코드 실수라기보다, 실패를 너무 늦게 발견하도록 파이프라인이 설계돼 있기 때문입니다.

1) 검증은 2단계로 분리

• 빌드 타임 검증: 필수 키 존재 여부, 형식(URL/숫자/불리언)
• 런타임 검증: 실제 연결 대상(DB/Redis/API) 접근 가능 여부

이 둘을 섞으면 어디서 깨졌는지 모호해집니다. 분리해두면 복구가 빨라집니다.

2) 바로 적용 순서

1. env.schema.ts에 필수값/형식/범위를 스키마로 정의
2. 앱 시작 시 한 번만 validateEnv() 호출
3. NEXT_PUBLIC_*와 서버 전용 키를 스키마 자체에서 분리
4. CI에서 next build 전에 env 검증 스텝 실행
5. 배포 직전 env.example과 실제 시크릿 목록 diff 확인

3) 최소 코드 예시

import { z } from 'zod'

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  NEXT_PUBLIC_APP_URL: z.string().url(),
})

export const env = EnvSchema.parse(process.env)

중요한 건 에러 메시지입니다. invalid env 대신 DATABASE_URL 누락처럼 바로 행동 가능한 문구로 남겨야 운영 속도가 납니다.

4) 릴리스 당일 체크리스트

• 신규 환경변수가 롤백 버전에도 안전한가
• 키 회전(rotate) 중인 시크릿이 남아 있지 않은가
• 배포 직후 핵심 API 3개를 실제 호출해 런타임 검증했는가
• 초기 10분 에러 로그가 시크릿 이슈인지 코드 이슈인지 분류됐는가

환경변수 검증은 "설정 관리"가 아니라 "배포 품질 게이트"입니다. 실패를 앞당기면 장애는 눈에 띄게 줄어듭니다.