import.meta.env.VITE_* is undefined
빠른 답변
- 이 오류는 무엇인가요?
- Vite 애플리케이션에서 import.meta.env의 환경 변수가 undefined로 보일 때 변수 이름·모드·빌드 시점을 확인합니다.
- 이 문서에서 확인할 수 있는 범위는 어디까지인가요?
- Vite는 클라이언트 코드에 노출할 환경 변수만 정해진 접두사를 사용해 import.meta.env에 넣습니다. 변수 이름, 실행 모드와 개발 서버 재시작 여부가 실제 값과 일치하는지 확인하며 비밀값을 VITE_ 변수로 노출하지 않습니다.
- 무엇을 먼저 확인해야 하나요?
- 로그 또는 화면에서 `import.meta.env.VITE_* is undefined` 또는 빈 값이 보이는지 확인합니다.
이 문서의 범위
이 문서는 화면·로그의 오류 원문 또는 상태를 공식 자료와 대조하는 데 사용합니다. 이 문구만으로 실제 원인이나 변경 방법을 확정하지 않으며, 아래 관련 기술 문서에서 적용 환경을 추가로 확인해야 합니다.
현재 증상
- 애플리케이션 오류 메시지
- 빌드 성공, 배포 실패
먼저 확인할 항목
로그 또는 화면에서 `import.meta.env.VITE_* is undefined` 또는 빈 값이 보이는지 확인합니다.
`.env` 변수 이름이 `VITE_` 접두사를 사용하는지 확인합니다.
`vite`와 `vite build`가 어떤 mode로 실행됐는지 확인합니다.
환경 변수 파일을 수정한 뒤 개발 서버를 다시 시작했는지 확인합니다.
피해야 할 조치
주의
- 비밀번호·개인 키·서버 전용 토큰을 `VITE_` 변수로 만들지 않습니다.
- 브라우저에서 사용되는 값은 빌드 결과에 포함될 수 있으므로 공개 가능 여부를 먼저 확인합니다.
오류 원문·상태 확인 범위
확인 방법
- 브라우저 콘솔 또는 화면에 표시된 변수 이름과 실제
.env변수 이름을 비교합니다. - 클라이언트에 노출할 값이
VITE_접두사를 사용하는지 확인합니다. vite개발 서버와vite build가 서로 다른 mode를 사용하지 않는지 확인합니다..env를 수정한 뒤 개발 서버를 다시 시작하고, 배포에서는 새 빌드가 생성됐는지 확인합니다.
Vite는 클라이언트 소스에서 접근할 환경 변수를 import.meta.env에 노출하지만 비밀값을 보호하는 저장소로 사용하지 않습니다. 값이 보이지 않는다고 서버 비밀값을 접두사만 바꿔 브라우저에 넣지 마십시오.
참고 자료
Env Variables and Modes (새 창에서 열림)
Vite · 공식 자료 · 확인 범위: import-meta-env, VITE-prefix, development-and-production-modes · 확인일: 2026-07-27