Next.js, 빌드 타임 환경 변수 한계 극복하는 '환경 변수 URL' 방식 적용기

Next.js의 기본 dotenv 방식은 빌드 타임에 환경 변수를 치환하므로, 여러 환경에 배포하려면 각 환경별로 빌드를 수행해야 한다. 이는 빌드 결과물이 특정 환경에 종속되며, npm 등 외부 모듈 관리 과정의 사이드 이펙트로 인해 빌드 결과물의 신뢰성이 낮아질 수 있다.

Next.js의 Runtime Configuration 기능은 런타임 주입을 지원하지만, SSG(Static Site Generation)와 호환되지 않고 렌더링 및 초기화 오버헤드를 유발하여 공식 문서에서 권장되지 않는다. 이에 따라 팀은 이러한 제약을 해결하기 위해 '환경 변수 URL' 방식을 도입했다.

구현 방식

환경 변수 URL 방식은 파싱된 환경 변수를 클라이언트에서 접근 가능한 스크립트 파일로 생성하여 public 폴더에 저장하는 구조다.

• 스크립트 생성: find-up과 dotenv를 이용해 환경별 .env 파일을 파싱하고, 이를 window.__ENV 객체에 할당하는 __ENV.js 스크립트를 /public 폴더에 생성한다.
• 서버 연동: 서버 측 사용을 위해 해당 환경 변수를 .env 파일로 복사하여 process.env에서 접근할 수 있게 한다.
• 클라이언트 주입: Document 컴포넌트에서 생성된 __ENV.js 스크립트를 로드하여 전역 변수로 주입한다.

이 방식을 통해 클라이언트는 window.__ENV, 서버는 process.env를 통해 동일한 환경 변수에 접근할 수 있으며, 빌드 타임 종속성을 제거하여 단일 빌드 아티팩트로 다양한 환경에 배포할 수 있게 되었다. 이는 빌드 과정의 불확실성을 줄이고 배포 신뢰성을 높이는 결과를 가져왔다.