Vite import.meta.env undefined 해결: VITE_ prefix 기준

• VITE_ prefix를 안 붙이면 왜 undefined인가요?
• .env, .env.local, .env.production 차이
• Vite 서버 재시작이 필요한 경우
• process.env와 import.meta.env 차이
• 배포 환경에서 환경변수가 안 잡히는 경우
• console.log({ mode: import.meta.env.MODE, apiUrlPresent: typeof import.meta.env.VITE_API_URL === “string” })로 확인하는 방법
• Vite 환경변수 undefined FAQ

같은 화면에서 undefined와 정상 값을 비교하는 재현

기존 Vite 앱의 복사본을 사용합니다. Vite 프로젝트 루트는 package.json과 vite.config가 있는 위치를 먼저 확인하고, envDir를 바꿨다면 그 디렉터리를 기준으로 합니다. 다음은 진단용 추가 파일이며 기존 앱 코드를 전체 교체하지 않습니다.

.env.development.local — 진단용 파일 전체; 실제 값 없음

DEMO_LABEL=prefix-missing

src/env-probe.js — 전체 파일

const label = import.meta.env.VITE_DEMO_LABEL;
console.log({
  mode: import.meta.env.MODE,
  labelPresent: typeof label === "string"
});

기존 엔트리 파일의 import들 아래에 import "./env-probe.js";를 추가합니다. npm run dev로 개발 서버를 시작하고 콘솔에서 mode: development, labelPresent: false를 기대합니다. TypeScript 엔트리에서 JS import 정책이 막히면 파일을 .ts로 만들고 import 확장자도 프로젝트 규칙에 맞춥니다.

수정은 .env.development.local의 키를 아래처럼 교체하는 것 하나입니다. 파일을 저장한 뒤 서버를 종료하고 다시 시작해야 새 env를 읽습니다.

.env.development.local — 수정 후 전체 파일

VITE_DEMO_LABEL=prefix-fixed

이제 labelPresent는 true여야 합니다. 이 재현은 prefix와 서버 재시작만 검증합니다. production build에는 development.local이 적용되지 않으므로 같은 공개 테스트 키를 .env.production.local에 별도로 넣고 npm run build 후 preview로 확인해야 합니다. 일반적인 Vite template에 preview script가 없다면 package.json scripts를 먼저 확인하세요.

검사 후 probe import·파일과 demo 전용 env 항목만 제거합니다. 기존 env 파일 전체를 지우지 않습니다. 실제 secret이 undefined라고 VITE_를 붙이는 것은 해결이 아닙니다. 브라우저에서 쓰면 안 되는 값은 서버 API로 옮겨야 합니다.

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	모든 mode에서 로드하는 로컬 덮어쓰기	VITE_API_URL=http://localhost:3000	Git 제외 권장. 배포 환경에는 자동 반영되지 않습니다.
.env.production	배포 환경	VITE_API_URL=https://api.example.com	빌드 시 적용. 배포 플랫폼 환경변수와 충돌 여부를 확인합니다.

.env.local은 Git에서 제외하는 개발자별 값에 적합하며, 파일이 존재하면 production을 포함한 모든 mode에서 로드됩니다. 개발 mode에만 적용하려면 .env.development.local을 사용합니다. 팀 공통 기본값은 .env, production build 기준 값은 .env.production 또는 배포 플랫폼 환경변수로 관리하는 편이 안전합니다.

Vite 서버 재시작이 필요한 경우

Vite 개발 서버가 실행 중일 때 env 파일을 수정하면 값이 즉시 반영되지 않을 수 있습니다. 특히 새 환경변수를 추가했거나 이름을 바꾼 경우에는 dev server를 껐다가 다시 실행해야 합니다.

1. .env, .env.local, .env.production 파일을 저장합니다.
2. 실행 중인 Vite dev server를 종료합니다.
3. npm run dev, pnpm dev, yarn dev 중 프로젝트 명령으로 다시 실행합니다.
4. 브라우저 새로고침 후 import.meta.env 값을 다시 확인합니다.

# 예시
Ctrl + C
npm run dev

process.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가 필요합니다.

1. 배포 플랫폼의 Environment Variables 설정에 VITE_ prefix가 붙은 키가 있는지 확인합니다.
2. Production, Preview, Development 환경 구분이 있는 플랫폼이라면 실제 배포 대상에 값이 들어 있는지 봅니다.
3. 환경변수 수정 후 새 배포를 실행합니다.
4. 빌드 로그에서 env 값 자체를 노출하지 말고, 키 존재 여부만 확인합니다.

보안상 API secret, private key, service account key 같은 비밀값은 VITE_로 노출하면 안 됩니다. VITE_ 값은 브라우저 번들에 포함될 수 있으므로 공개되어도 되는 값만 넣어야 합니다.

console.log({ mode: import.meta.env.MODE, apiUrlPresent: typeof import.meta.env.VITE_API_URL === “string” })로 확인하는 방법

문제가 계속되면 실제 브라우저에서 import.meta.env를 출력해 키가 존재하는지 확인합니다. 단, 운영 환경에서 전체 env 객체를 오래 남겨두면 불필요한 정보가 노출될 수 있으므로 확인 후 제거합니다.

console.log({ mode: import.meta.env.MODE, apiUrlPresent: typeof import.meta.env.VITE_API_URL === "string" });
console.log(import.meta.env.VITE_API_URL);

값이 아예 없다면 prefix, 파일 위치, 서버 재시작 문제를 보고, 로컬에는 있는데 배포에 없다면 배포 플랫폼 환경변수 등록과 재빌드를 확인합니다.

앱의 Vite 개발 서버에서는 정상인데 Storybook에서만 환경변수나 import가 깨진다면 두 환경의 alias와 builder 설정을 비교해야 합니다. 동적 모듈 로딩 오류가 함께 보이면 Storybook Vite Failed to fetch dynamically imported module 해결법의 캐시·경로·viteFinal 점검 순서를 확인합니다.

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 등 배포 환경까지 함께 점검하려면 프론트엔드 배포 오류 체크리스트를 같이 보면 좋습니다.

관련 글을 대표 허브 기준으로 이어서 보기

이 글과 비슷한 문제는 프론트엔드 배포 오류 체크리스트에서 전체 흐름을 먼저 확인하면 검색 의도와 해결 순서를 더 분명하게 나눌 수 있습니다.

• 대표 허브: 프론트엔드 배포 오류 체크리스트
• 프론트엔드 배포 로드맵
• Vercel Next.js 배포 실패 체크리스트
• Vercel 404 NOT_FOUND 오류 해결
• Next.js 환경변수 적용 오류 해결
• Expo EAS Build 오류 해결

공식 문서

• Vite 공식 문서