Runtime 환경 변수 설정으로 빌드 프로세스 개선하기

Next.js의 빌드 타임 환경 변수 주입 방식의 한계를 짚고, 단일 빌드 결과물로 여러 환경(dev/stage/prod)에 런타임 환경 변수를 주입하는 실용적인 해결책을 제시한다. 환경마다 별도 빌드를 반복하는 비효율을 없애려는 팀에 직접적인 가이드가 된다.

핵심 포인트 - 문제: Next.js의 dotenv 기반 환경 변수는 빌드 타임에 번들에 인라인되어 환경마다 별도 빌드가 필요 - Next.js Runtime Configuration 공식 한계: SSG(Static Site Generation) 미지원, 공식 문서도 사용 비권장 - 해결 전략: 환경 변수를 URL로 제공하고 window.__ENV에 주입하는 별도 스크립트 파일을 public 디렉토리에 배치 - 구현 흐름: dotenv로 .env 파싱 → /public/__ENV.js에 window.__ENV = {...} 스크립트 파일 생성 → 대상 .env 파일 복사 → yargs 기반 next-env CLI 명령 실행 - 1회 빌드 후 환경별 __ENV.js만 교체해 런타임 변수 주입 → CI/CD 빌드 시간·비용 절감 - 기존 process.env.XXX 접근 코드를 window.__ENV.XXX로 점진적으로 마이그레이션 가능

상세 정리 - Next.js는 빌드 시 process.env.NEXT_PUBLIC_* 를 번들에 하드코딩해 런타임에 값 변경 불가 - 환경마다 빌드를 다시 돌리면 빌드 캐시가 무효화되고, 동일 코드인데도 환경별 이미지가 달라짐 - __ENV.js는 HTML head에 script src="/__ENV.js" 형태로 삽입해 Next.js 앱보다 먼저 로드 - dotenv 라이브러리로 .env 파일을 파싱해 JSON 직렬화 후 window.__ENV = {...} 형태 스크립트 파일로 저장 - yargs CLI 래퍼로 next-env --env=prod 형태의 명령어를 제공해 개발자 경험 개선 - 배포 시 환경별 __ENV.js만 정적 파일 서버에 올리면 코드 변경 없이 환경 전환 가능 - SSR 환경에서는 typeof window !== undefined 체크로 서버 사이드 접근 방지 필요 - 보안 주의: __ENV.js는 브라우저에 노출되므로 비밀값(API Secret, DB 비밀번호)은 절대 포함 금지 - 이 패턴은 Docker 컨테이너 기반 배포에서 환경별 컨테이너 이미지 분리 필요를 없애는 데도 유용

왜 읽나: 환경마다 별도 빌드 없이 단일 빌드 결과물로 여러 환경을 커버하는 실용적 패턴을 단계별 구현 코드와 함께 익힐 수 있다.