AI가 만든 코드가 로컬에서는 되는데 배포에서 환경 변수를 못 읽어요
로컬 .env에서는 동작하지만 배포 빌드 또는 브라우저에서 환경 변수가 undefined일 때 프레임워크별 노출 범위를 확인합니다.
빠른 답변
변수의 이름·파일·배포 환경과 클라이언트 노출 접두사를 확인하고, 비밀값을 공개 접두사로 옮기지 않는 것이 우선입니다.
- 적용 범위
- 이 가이드의 시작 증상과 각 분기 조건이 일치하는 경우문맥: 바이브 코딩
- 출처 확인일
- 2026-08-04
- 최종 검토
- 2026-08-04
- 수정일
- 2026-08-04
- 정정 이력
- 2026-07-29 이후 기록 없음
- 대상
- 사이트 운영자, 웹 에이전시, 프리랜서
이 가이드가 맞는 경우
- 빌드 실패
- 애플리케이션 오류 메시지
- 설정 누락
상황별 다음 단계
호스팅사·개발자에게 전달할 내용
변경 전 기록
- 변수 이름·대상 환경·빌드 명령과 실제 읽기 위치를 기록합니다.
- 환경변수 값·토큰·비밀번호는 기록하지 않습니다.
알아둘 점
확인 순서
- 변수 이름을 값 대신 기록하고,
.env파일·배포 환경·실행 단계 중 어디에서 읽는지 표시합니다. - Vite라면 브라우저에 필요한 변수만
VITE_접두사를 사용하는지 확인합니다. - Next.js라면 브라우저에 공개해도 되는 값만
NEXT_PUBLIC_을 사용하고, 서버 전용 비밀값은 서버 코드에서만 읽는지 확인합니다. - 문구가 일치하면 Environment variable not found: ., import.meta.env.VITE_* is undefined, Missing Env Value를 확인합니다.
환경 변수의 실제 값, 토큰, 비밀번호를 로그나 이슈에 붙여 넣지 마십시오. 이미 브라우저 번들에 포함된 비밀값은 이름을 바꾸는 것만으로 폐기되지 않으므로 교체 여부를 별도로 검토해야 합니다.
참고 자료
Env Variables and Modes | Vite (새 창에서 열림)
Vite · 공식 자료 · 확인 범위: Vite는 클라이언트에 노출할 변수에 VITE_ 접두사를 사용하며, 접두사 변수는 빌드 시 정적으로 치환됩니다. · 확인일: 2026-08-04
Guides: Environment Variables | Next.js (새 창에서 열림)
Next.js · 공식 자료 · 확인 범위: NEXT_PUBLIC_ 접두사가 붙은 Next.js 변수는 브라우저 번들에 포함될 수 있으므로 비밀값에 사용하지 않아야 합니다. · 확인일: 2026-08-04