Vite mode에 맞는 환경 변수 파일이 로드되지 않음

적용 범위

이 문서는 Vite 개발·배포 명령의 mode와 환경 변수 파일이 달라 예상한 값이 주입되지 않는 상황을 확인합니다. Vite는 mode에 따라 환경 파일을 선택하고, 동일한 변수는 우선순위가 높은 파일의 값을 사용합니다.

변경 없이 확인할 항목

1. 실행한 명령과 --mode 값을 기록합니다.
2. 해당 mode에 적용되는 파일 이름과 변수 이름만 비교합니다.
3. 개발 서버 재시작 또는 배포 재빌드 뒤 값이 바뀌었는지 확인합니다.

환경 파일의 실제 값은 공개하지 않습니다. 클라이언트에서 사용하는 변수는 빌드 결과에 포함될 수 있으므로 비밀값을 넣지 않습니다.

공식 근거

Vite Env Variables and Modes (새 창에서 열림)

관찰값 기록

문제가 발생한 URL 또는 화면, 표시 시각, 운영 환경과 최근 변경 사항을 먼저 기록합니다. 화면이나 로그에 오류 문구가 일부만 보이면 앞뒤 문장을 보존하고 비밀번호·토큰·쿠키·개인정보는 가립니다.

다음 항목을 실제 값과 함께 확인합니다.

1. 실행한 vite 또는 vite build --mode <mode> 명령과 mode를 기록합니다.
2. mode에 대응하는 .env.[mode]와 .env.[mode].local 파일의 변수 이름만 비교합니다.
3. 개발 서버 재시작 또는 배포 재빌드 뒤 동일한 변수 값이 나오는지 확인합니다.

판정 기준

오류 문구가 일치해도 같은 원인이 확정되는 것은 아닙니다. 웹서버·런타임·운영체제·플랫폼과 최근 변경 사항을 비교하고, 기대한 관찰값이 나오지 않으면 다음 단계로 넘어가지 않습니다. 이 문서는 출처가 확인한 범위만 설명하며, 범위를 벗어난 원인과 조치는 단정하지 않습니다.

안전한 다음 확인

설정·권한·데이터를 변경하기 전에 백업과 되돌리기 방법을 기록합니다. 운영 환경의 방화벽 전체 해제, 인증서 검증 우회, 데이터 삭제, 비밀값 공개를 기본 조치로 사용하지 않습니다. 확인 결과가 문서의 조건과 다르면 관련 Platform·Component 문서와 공식 출처를 먼저 확인합니다.