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

오류 재현

.env.local에 다음 값을 넣었다고 가정합니다.

API_URL=http://localhost:4000

코드에서 읽습니다.

console.log(import.meta.env.API_URL);

결과는 undefined가 될 수 있습니다.

Vite는 기본적으로 VITE_ 접두사가 붙은 변수를 클라이언트 코드에 노출합니다.

따라서 다음과 같이 바꿉니다.

VITE_API_URL=http://localhost:4000

console.log(import.meta.env.VITE_API_URL);

왜 접두사가 필요한가

브라우저에서 실행되는 JavaScript는 사용자에게 전달됩니다.

.env 파일에 서버 비밀번호가 있다고 해서 자동으로 안전한 것이 아닙니다.

Vite가 모든 환경 변수를 자동으로 클라이언트에 노출하면 실수로 비밀 값이 번들에 포함될 수 있습니다.

그래서 기본 접두사를 사용해 “이 값은 클라이언트에 공개해도 된다”는 경계를 만듭니다.

VITE_API_URL
→ 클라이언트 노출 가능

DB_PASSWORD
→ 기본 설정에서는 import.meta.env로 클라이언트에 노출하지 않음

단, 이름에 VITE_가 붙었다고 값이 안전해지는 것은 아닙니다.

VITE_가 붙은 값은 공개될 수 있다고 가정해야 합니다.

Vite가 기본으로 제공하는 값

Vite는 사용자 정의 변수 외에도 실행 상태를 확인할 수 있는 값을 제공합니다.

console.log(import.meta.env.MODE);
console.log(import.meta.env.DEV);
console.log(import.meta.env.PROD);
console.log(import.meta.env.BASE_URL);

개발과 배포 코드를 구분할 때 사용할 수 있습니다.

if (import.meta.env.DEV) {
  console.log('development mode');
}

환경 변수는 문자열이다

VITE_RETRY_COUNT=3
VITE_FEATURE_FLAG=true

const retryCount = Number(import.meta.env.VITE_RETRY_COUNT);
const featureFlag =
  import.meta.env.VITE_FEATURE_FLAG === 'true';

타입 변환 없이 숫자처럼 계산하면 예상하지 못한 결과가 나올 수 있습니다.

envPrefix를 바꿀 수 있나요

Vite 설정의 envPrefix로 기본 접두사를 변경할 수 있습니다.

하지만 특별한 이유가 없다면 기본 VITE_를 유지하는 편이 이해하기 쉽습니다.

특히 envPrefix를 빈 문자열로 설정해 모든 환경 변수를 노출하는 방식은 사용하지 않습니다.

오류 해결 순서

import.meta.env가 undefined일 때 다음 순서로 확인합니다.

1. 환경 변수 이름
2. VITE_ 접두사
3. .env 파일 위치
4. 현재 mode
5. 개발 서버 재시작
6. import.meta.env 철자
7. vite.config의 envDir/envPrefix 변경 여부

자주 발생하는 실수

process.env를 사용합니다

Vite 클라이언트 코드에서는 import.meta.env를 기준으로 사용합니다.

import.meta.env.VITE_API_URL

.env.local 수정 후 서버를 재시작하지 않았습니다

Ctrl + C
pnpm dev

비밀키에 VITE_를 붙였습니다

브라우저에서 사용할 값이 아니라면 클라이언트 변수로 만들지 않습니다.

잘못된 예
VITE_DATABASE_PASSWORD=...

올바른 방향
서버 전용 환경에서만 DB_PASSWORD 사용

boolean처럼 보이는 값을 문자열로 비교하지 않았습니다

const enabled =
  import.meta.env.VITE_FEATURE_FLAG === 'true';

학습 완료 체크리스트

• import.meta.env의 역할을 설명할 수 있습니다.
• VITE_ 접두사가 필요한 이유를 이해했습니다.
• 클라이언트 환경 변수에 비밀값을 넣지 않습니다.
• mode와 NODE_ENV를 같은 개념으로 단정하지 않습니다.
• 환경 변수 값을 필요한 타입으로 변환할 수 있습니다.
• undefined 오류를 접두사부터 순서대로 확인할 수 있습니다.

.env
.env.local
.env.development
.env.example

const apiUrl = import.meta.env.VITE_API_URL;
const appName = import.meta.env.VITE_APP_NAME;

if (!apiUrl) {
  throw new Error('VITE_API_URL 환경 변수가 필요합니다.');
}

export const env = {
  apiUrl,
  appName: appName || 'TaskFlow',
};

import { env } from './config/env';

console.log(env.apiUrl);

pnpm --filter @taskflow/web exec vite --mode staging

dev-env-step-03-env-contract

.env.example
src/config/env.js
src/main.js 또는 앱 진입 파일

VITE_API_URL=https://api.example.invalid
VITE_APP_NAME=TaskFlow

const apiUrl = import.meta.env.VITE_API_URL;
const appName = import.meta.env.VITE_APP_NAME;

if (!apiUrl) {
  throw new Error('VITE_API_URL 환경 변수가 필요합니다.');
}

export const env = {
  apiUrl,
  appName: appName || 'TaskFlow',
};

.env 파일은 있지만 코드에서 직접 검증하지 않음
변수 이름이 틀려도 화면 실행 후에야 문제 발견

VITE_ 접두사 기준 확정
환경 변수 모듈 분리
필수 값 누락 시 즉시 오류
브라우저 공개 값과 서버 비밀 값 경계 명확화

pnpm dev

dev-env-step-04-vite-env

node_modules/
dist/
storybook-static/
.env.local
.env.*.local

VITE_API_URL=https://api.example.invalid
VITE_APP_NAME=TaskFlow

<!doctype html>
<html lang="ko">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>TaskFlow 개발환경</title></head>
<body><main id="app"></main><script type="module" src="/src/main.js"></script></body>
</html>

{
  "name": "@taskflow/web",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build"
  },
  "devDependencies": {
    "vite": "8.3.0"
  }
}

const apiUrl = import.meta.env.VITE_API_URL;
const appName = import.meta.env.VITE_APP_NAME;

if (!apiUrl) {
  throw new Error('VITE_API_URL 환경 변수가 필요합니다.');
}

export const env = {
  apiUrl,
  appName: appName || 'TaskFlow',
};

import './style.css';
import { env } from './config/env.js';

const app = document.querySelector('#app');
const title = document.createElement('h1');
title.textContent = env.appName;
const status = document.createElement('p');
status.textContent = '개발환경 스타터가 실행 중입니다.';
const api = document.createElement('p');
api.id = 'api-url';
api.textContent = `API URL: ${env.apiUrl}`;
app.append(title, status, api);

body { margin: 0; color: #202020; background: #f6f6f6; font: 16px/1.6 system-ui, sans-serif; }
main { max-width: 720px; margin: 64px auto; padding: 24px; }
h1 { font-size: 30px; font-weight: 500; }
p { overflow-wrap: anywhere; }

# TaskFlow 개발환경

이 스타터는 개발환경 진단을 위한 최소 Vite/vanilla JavaScript 앱입니다. 할 일 관리 기능이나 API 서버는 포함하지 않습니다.

Node.js 24.19.0, pnpm 11.19.0으로 검증했습니다. 루트는 pnpm만 사용하며 apps/*만 workspace입니다. labs의 npm/Yarn/pnpm 실습은 독립 프로젝트입니다.

## 2회차

메인 앱은 pnpm을 유지합니다. labs/yarn-modern은 독립 Yarn 실습입니다.

## 3회차

apps/web/.env.example을 apps/web/.env.local로 복사합니다. .invalid 주소는 표시만 하며 실제 API 호출은 하지 않습니다. 공개 샘플값만 제공하고 로컬 파일은 ZIP에서 제외합니다.

## 4회차

Vite 루트는 apps/web입니다. env.js가 필수 VITE_API_URL을 검사하고 화면에 공개 URL을 표시합니다.

{
  "name": "taskflow",
  "private": true,
  "packageManager": "pnpm@11.19.0",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "dev": "pnpm --filter @taskflow/web dev",
    "build": "pnpm --filter @taskflow/web build"
  }
}

packages:
  - "apps/*"

# TaskFlow 개발환경 04 완료 체크포인트

Node.js 24.19.0 / pnpm 11.19.0 검증 기준입니다. pnpm을 별도로 설치한 환경에서 실행하세요. ZIP에는 node_modules, dist, 로컬 환경 변수, 실제 비밀값이 없습니다.

1. 이 폴더에서 `pnpm install --frozen-lockfile`
2. PowerShell: `Copy-Item apps/web/.env.example apps/web/.env.local` 또는 macOS/Linux: `cp apps/web/.env.example apps/web/.env.local`
3. `pnpm dev` 후 http://127.0.0.1:5173 확인
4. `pnpm build`

ESLint는 5회차부터 추가되므로 이 체크포인트에는 lint 명령이 없습니다.

apps/web가 Vite 루트입니다. 환경 변수도 이 폴더에 둡니다. 표시용 API 주소에 실제 요청을 보내지 않습니다. labs는 메인 workspace에서 제외되어 각 폴더에서 별도 설치합니다.

원문 단계별 전체 파일과 실행 검증 범위는 docs/development-environment.md를 확인하세요.

nodeLinker: node-modules

{
  "name": "taskflow-yarn-lab",
  "private": true,
  "type": "module",
  "packageManager": "yarn@4.18.0",
  "scripts": {
    "dev": "node src/main.js",
    "lint": "node --check src/main.js"
  }
}

console.log('TaskFlow Yarn 독립 실습');

다음 학습

이제 설치와 환경 변수는 재현할 수 있지만 코드 품질 검사를 자동으로 확인하는 기준이 없습니다.

다음 글에서는 eslint.config.js flat config를 연결하고 “VS Code에서는 경고가 없는데 CLI에서는 실패하는 문제”까지 구분합니다.

다음 글: ESLint flat config 규칙 적용 안됨 해결: eslint.config.js 기준

공식 문서

• Vite Env Variables and Modes: https://vite.dev/guide/env-and-mode
• Vite envPrefix: https://vite.dev/config/shared-options