Vite 환경 변수가 undefined로 보여요
Vite에서 import.meta.env 값이 undefined이거나 비어 있을 때 변수 접두사·실행 mode·재빌드 여부를 확인합니다.
빠른 답변
Vite 환경 변수가 보이지 않으면 클라이언트에 노출할 변수의 VITE_ 접두사, 실행 mode에 맞는 env 파일, 개발 서버 재시작과 배포 재빌드를 순서대로 확인합니다. 비밀값을 VITE_ 변수로 노출하지 않습니다.
이 가이드가 맞는 경우
- 애플리케이션 오류 메시지
- 빌드 성공, 배포 실패
상황별 다음 단계
호스팅사·개발자에게 전달할 내용
변경 전 기록
- 실제 변수 이름, 실행 명령과 mode, 발생한 빌드 시각을 전달합니다.
- API 비밀 키와 토큰 값 자체는 전달하지 않습니다.
- 환경 변수를 수정한 뒤 개발 서버 또는 배포 빌드를 다시 실행했는지 기록합니다.
알아둘 점
이 문서는 Vite 환경 변수가 undefined로 보여요라는 시작 상황에서 변수 이름과 빌드 시점을 확인하는 순서를 제공합니다. 브라우저에서 읽는 값은 빌드 결과에 포함될 수 있으므로 비밀값을 넣지 않습니다.
먼저 확인할 순서
- 소스에서 접근하는 이름과
.env의 이름이 정확히 같은지 비교합니다. - 브라우저에 노출할 값만
VITE_접두사를 사용하는지 확인합니다. vite와vite build가 사용하는 mode에 맞는.env파일인지 확인합니다..env를 수정한 뒤 개발 서버를 다시 시작하고, 배포에서는 새 빌드를 생성합니다.
콘솔에 import.meta.env.VITE_* is undefined가 표시되면 import.meta.env.VITE_* is undefined 문서를 확인합니다. 그 외 오류는 환경 변수 이름과 실행 명령을 원문 그대로 기록해 별도 검토하세요.
참고 자료
Env Variables and Modes (새 창에서 열림)
Vite · 공식 자료 · 확인 범위: import-meta-env, VITE-prefix, development-and-production-modes · 확인일: 2026-07-27