Next.js env
변수 노출 범위 결정표
변수 이름과 실행 위치를 먼저 나누면 어디서 읽히는지, 언제 브라우저 번들에 고정되는지 빠르게 판단할 수 있다.
읽히는 위치와 고정 시점
decision table
변수 종류
서버 실행
브라우저 번들
로컬 .env.local
Vercel 환경
서버 전용 변수
DATABASE_URL, API_SECRET
읽음
서버 컴포넌트, 라우트 핸들러, 빌드 작업
노출 안 함
클라이언트 코드에서 직접 사용 불가
next dev
로컬 개발 서버가 우선 읽음
런타임
Development, Preview, Production 값 주입
NEXT_PUBLIC_ 변수
NEXT_PUBLIC_API_URL
읽음
서버에서도 process.env로 접근 가능
고정
빌드 시 클라이언트 번들에 치환
로컬 값
개발 중 브라우저 코드에 반영
빌드 값
Preview와 Production 빌드마다 따로 고정
Vercel Development 값은 주로 `vercel dev`의 로컬 실행에 대응하고, Preview와 Production 값은 각 배포 빌드에 주입된다. 공개 변수는 배포 후 값을 바꾸는 것만으로 기존 브라우저 번들이 자동 변경되지 않는다.