NEXT_PUBLIC_* 환경 변수 규칙¶
Next.js는 환경 변수가 빌드 결과물에 포함될 수 있는 구조를 가진다.
이는 Node.js(Express)와 비교했을 때 가장 위험도가 높은 운영 차이점 중 하나다.
특히 NEXT_PUBLIC_* 접두사가 붙은 환경 변수는
클라이언트 JavaScript 번들에 직접 포함되어 브라우저에 노출된다.
1. Node.js(Express)의 환경 변수 특성¶
process.env.*는 서버 런타임에서만 접근 가능- 클라이언트로 전달되지 않음
- 잘못 설정하더라도:
- 값 수정
- 프로세스 재시작
으로 복구 가능
2. Next.js 환경 변수 동작 방식¶
NEXT_PUBLIC_*접두사가 붙은 변수는:- 빌드 시점에 코드로 치환됨
- 클라이언트 JS 번들에 하드코딩됨
- 브라우저 개발자 도구에서 누구나 확인 가능
즉, 이는 “환경 변수”라기보다
빌드 타임 상수(public constant) 에 가깝다.
3. 빌드 타임 vs 런타임 차이¶
NEXT_PUBLIC_*값 변경 시:- ❌ 런타임 env 수정 → 효과 없음
- ❌ 서버 재시작 → 효과 없음
- ⭕ 반드시 재빌드 필요
한 번 배포된 빌드 산출물에 포함된 값은
사후적으로 숨기거나 회수할 수 없다.
4. 운영 기준 (Baseline)¶
- 다음 정보는 절대
NEXT_PUBLIC_*에 사용하지 않는다- API Secret / Token
- DB 접속 정보
- 내부 시스템 식별자
- 인증 관련 값
NEXT_PUBLIC_*에는:- 공개 URL
- 기능 플래그
- 공개 가능한 환경 구분 값만 사용한다
5. 운영 체크리스트¶
-
NEXT_PUBLIC_*변수 존재 여부 점검 - 민감 정보 포함 여부 확인
- 값 변경 시 재빌드 필요성 인지
- 유출 시 즉시 키 폐기 및 재발급 계획 수립
중요:
NEXT_PUBLIC_*에 민감 정보가 포함된 상태로 배포되었다면
이는 설정 실수가 아니라 보안 사고로 간주한다.