Vite mode에 맞는 환경 변수 파일이 로드되지 않음
Vite 개발·배포 명령의 mode와 환경 변수 파일이 달라 예상한 값이 주입되지 않는지 확인하는 문서입니다.
빠른 답변
- 우선 확인할 원인
- Vite는 실행 mode에 따라 `.env`, `.env.local`, `.env.[mode]`, `.env.[mode].local` 파일을 다르게 적용할 수 있으므로 실제 명령의 mode와 파일 이름을 먼저 비교해야 합니다. 값이 공개되어야 하는 클라이언트 변수만 `VITE_` 접두사를 사용합니다.
- 먼저 확인할 항목
- 실행한 `vite` 또는 `vite build --mode <mode>` 명령과 mode를 기록합니다.
- 적용 범위
- 현재 증상과 본문에 적은 관찰 조건이 함께 확인된 경우문맥: 바이브 코딩
- 출처
- Vite
- 출처 확인일
- 2026-07-29
- 최종 검토
- 2026-07-29
- 수정일
- 2026-07-29
- 정정 이력
- 2026-07-29 이후 기록 없음
- 관련 기술
현재 증상
- 애플리케이션 오류 메시지
- 빌드 성공, 배포 실패
먼저 확인할 항목
실행한 `vite` 또는 `vite build --mode <mode>` 명령과 mode를 기록합니다.
mode에 대응하는 `.env.[mode]`와 `.env.[mode].local` 파일의 변수 이름만 비교합니다.
개발 서버 재시작 또는 배포 재빌드 뒤 동일한 변수 값이 나오는지 확인합니다.
피해야 할 조치
주의
- 비밀번호·개인 키·서버 전용 토큰을 `VITE_` 변수로 노출하지 않습니다.
- 환경 파일의 실제 값과 개인정보를 로그나 문의 자료에 포함하지 않습니다.
환경별 원인과 조치
적용 범위
이 문서는 Vite 개발·배포 명령의 mode와 환경 변수 파일이 달라 예상한 값이 주입되지 않는 상황을 확인합니다. Vite는 mode에 따라 환경 파일을 선택하고, 동일한 변수는 우선순위가 높은 파일의 값을 사용합니다.
변경 없이 확인할 항목
- 실행한 명령과
--mode값을 기록합니다. - 해당 mode에 적용되는 파일 이름과 변수 이름만 비교합니다.
- 개발 서버 재시작 또는 배포 재빌드 뒤 값이 바뀌었는지 확인합니다.
환경 파일의 실제 값은 공개하지 않습니다. 클라이언트에서 사용하는 변수는 빌드 결과에 포함될 수 있으므로 비밀값을 넣지 않습니다.
공식 근거
참고 자료
Env Variables and Modes (새 창에서 열림)
Vite · 공식 자료 · 확인 범위: mode-specific-env-files, environment-file-priority, VITE-prefix · 확인일: 2026-07-29