Vite import.meta.env undefined 오류를 가장 빨리 찾는 순서
Vite에서 import.meta.env 값이 undefined라면 변수명 prefix, env 파일 위치, mode별 파일, dev server 재시작, 배포 환경변수 등록 여부를 순서대로 확인해야 합니다. 이 글은 process.env와 import.meta.env 차이까지 함께 정리합니다.
- VITE_ prefix를 안 붙이면 왜 undefined인가요?
- .env, .env.local, .env.production 차이
- Vite 서버 재시작이 필요한 경우
- process.env와 import.meta.env 차이
- 배포 환경에서 환경변수가 안 잡히는 경우
- console.log(import.meta.env)로 확인하는 방법
- Vite 환경변수 undefined FAQ
VITE_ prefix를 안 붙이면 왜 undefined인가요?
Vite는 클라이언트 번들에 노출할 환경변수만 import.meta.env로 제공합니다. 이때 기본 규칙은 VITE_ prefix입니다. 그래서 API_URL처럼 일반 이름으로 만든 값은 브라우저 코드에서 import.meta.env.API_URL로 읽어도 undefined가 됩니다.
# 잘못된 예시: 클라이언트 코드에서 import.meta.env.API_URL로 읽히지 않음
API_URL=https://api.example.com
# 올바른 예시
VITE_API_URL=https://api.example.com// 올바른 접근
const apiUrl = import.meta.env.VITE_API_URL;해결 순서는 env 파일의 키 이름 확인 → 코드에서 참조하는 이름 확인 → dev server 재시작 → 브라우저에서 실제 값 확인입니다.
.env, .env.local, .env.production 차이
Vite는 실행 mode에 따라 여러 env 파일을 읽습니다. 로컬에서는 값이 나오는데 production build에서 undefined라면 파일별 적용 시점과 배포 환경변수를 함께 확인해야 합니다.
| 파일명 | 사용 시점 | 예시 | 주의점 |
|---|---|---|---|
| .env | 전체 환경 | VITE_API_URL=https://api.example.com | 공통값. 민감한 값은 넣지 않습니다. |
| .env.local | 로컬 전용 | VITE_API_URL=http://localhost:3000 | Git 제외 권장. 배포 환경에는 자동 반영되지 않습니다. |
| .env.production | 배포 환경 | VITE_API_URL=https://api.example.com | 빌드 시 적용. 배포 플랫폼 환경변수와 충돌 여부를 확인합니다. |
.env.local은 로컬 개발자 환경에만 남기는 값에 적합합니다. 팀 공통 기본값은 .env, production build 기준 값은 .env.production 또는 배포 플랫폼 환경변수로 관리하는 편이 안전합니다.
Vite 서버 재시작이 필요한 경우
Vite 개발 서버가 실행 중일 때 env 파일을 수정하면 값이 즉시 반영되지 않을 수 있습니다. 특히 새 환경변수를 추가했거나 이름을 바꾼 경우에는 dev server를 껐다가 다시 실행해야 합니다.
.env,.env.local,.env.production파일을 저장합니다.- 실행 중인 Vite dev server를 종료합니다.
npm run dev,pnpm dev,yarn dev중 프로젝트 명령으로 다시 실행합니다.- 브라우저 새로고침 후
import.meta.env값을 다시 확인합니다.
# 예시
Ctrl + C
npm run devprocess.env와 import.meta.env 차이
Vite 프론트엔드 코드에서는 Node.js의 process.env를 그대로 쓰는 방식이 기본이 아닙니다. Create React App이나 Node 서버 코드에서 쓰던 습관으로 process.env.REACT_APP_API_URL 또는 process.env.API_URL을 사용하면 Vite 환경에서는 기대와 다르게 동작할 수 있습니다.
| 구분 | 주 사용 환경 | 예시 | 주의점 |
|---|---|---|---|
process.env | Node.js 서버, 일부 번들러 관습 | process.env.API_URL | Vite 클라이언트 코드에서는 기본 접근 방식이 아닙니다. |
import.meta.env | Vite 클라이언트 코드 | import.meta.env.VITE_API_URL | 브라우저 노출 값은 VITE_ prefix가 필요합니다. |
Next.js나 CRA에서 Vite로 옮긴 프로젝트라면 환경변수 이름과 접근 방식도 함께 바꿔야 합니다.
배포 환경에서 환경변수가 안 잡히는 경우
로컬에서는 값이 나오는데 Vercel, Netlify, Cloudflare Pages 같은 배포 환경에서 undefined라면 .env.local만 믿고 배포한 경우가 많습니다. 배포 플랫폼에는 환경변수를 별도로 등록해야 하며, 등록 후에는 새 build가 필요합니다.
- 배포 플랫폼의 Environment Variables 설정에
VITE_prefix가 붙은 키가 있는지 확인합니다. - Production, Preview, Development 환경 구분이 있는 플랫폼이라면 실제 배포 대상에 값이 들어 있는지 봅니다.
- 환경변수 수정 후 새 배포를 실행합니다.
- 빌드 로그에서 env 값 자체를 노출하지 말고, 키 존재 여부만 확인합니다.
보안상 API secret, private key, service account key 같은 비밀값은 VITE_로 노출하면 안 됩니다. VITE_ 값은 브라우저 번들에 포함될 수 있으므로 공개되어도 되는 값만 넣어야 합니다.
console.log(import.meta.env)로 확인하는 방법
문제가 계속되면 실제 브라우저에서 import.meta.env를 출력해 키가 존재하는지 확인합니다. 단, 운영 환경에서 전체 env 객체를 오래 남겨두면 불필요한 정보가 노출될 수 있으므로 확인 후 제거합니다.
console.log(import.meta.env);
console.log(import.meta.env.VITE_API_URL);값이 아예 없다면 prefix, 파일 위치, 서버 재시작 문제를 보고, 로컬에는 있는데 배포에 없다면 배포 플랫폼 환경변수 등록과 재빌드를 확인합니다.
Vite 환경변수 undefined FAQ
VITE_ prefix를 붙였는데도 undefined면 무엇을 보나요?
파일 위치, 변수명 오타, dev server 재시작 여부, mode별 env 파일 우선순위를 확인합니다. 코드에서 읽는 이름과 env 파일의 키가 정확히 같은지도 봐야 합니다.
.env.local 값은 배포에도 자동으로 들어가나요?
아닙니다. .env.local은 로컬 전용으로 쓰는 경우가 많고, 배포 플랫폼에는 별도로 환경변수를 등록해야 합니다.
process.env를 계속 쓰면 안 되나요?
Vite 클라이언트 코드에서는 import.meta.env를 기준으로 바꾸는 것이 좋습니다. 기존 CRA나 Node 코드에서 옮겨왔다면 환경변수 접근 방식을 함께 수정해야 합니다.
배포 환경변수 문제는 어디서 더 확인하나요?
Vercel, Expo 등 배포 환경까지 함께 점검하려면 프론트엔드 배포 오류 체크리스트를 같이 보면 좋습니다.