프론트엔드 환경변수(.env) 관리, 우선순위

1. 환경변수가 뭐길래?

환경변수(Environment Variable)는 빌드 시점에 코드에 주입되는 설정값이에요.
API 서버 주소, 서비스 이름, Firebase 키처럼 환경마다 달라지는 값을 코드에 직접 하드코딩하지 않기 위해 사용합니다.

 

2. .env 파일 구조와 우선순위

프론트엔드 빌드 도구들은 대부분 dotenv 규칙을 따릅니다. 즉, 파일명이 아래 순서로 있으면 뒤의 파일이 앞의 파일을 덮어씁니다.

우선순위	파일명	설명
1	.env	공통 설정 (모든 모드 공용)
2	.env.local	로컬 전용 (Git에 올리지 않음)
3	.env.[mode]	특정 모드용 (development, production 등)
4	.env.[mode].local	특정 모드 + 로컬용 (가장 높은 우선순위)

 

개발 시 적용 순서

.env → .env.local → .env.development → .env.development.local

 

3. 실행 모드(mode)

각 프레임워크는 명령어에 따라 기본 mode를 지정합니다.

명령어	mode	예시 적용 파일
npm run dev	development	.env, .env.local, .env.development, .env.development.local
npm run build	production	.env, .env.local, .env.production, .env.production.local

필요하다면 직접 지정도 가능

vite build --mode staging
next build --mode staging # 일부 프레임워크는 환경 변수만 바꿔서 실행

4. 프레임워크별 “접두사(prefix)” 규칙

보안상의 이유로, 클라이언트 코드(브라우저) 에 노출될 수 있는 환경변수는 각 프레임워크별로 특정 접두사(prefix) 를 강제합니다.

프레임워크	접두사	접근방법	비고
Vite	VITE_	import.meta.env.VITE_XXX	VITE_만 클라이언트 접근 가능
Create React App	REACT_APP_	process.env.REACT_APP_XXX	CRA 빌드 시점에 주입
Next.js	NEXT_PUBLIC_	process.env.NEXT_PUBLIC_XXX	NEXT_PUBLIC_만 브라우저에 노출
Nuxt.js	NUXT_PUBLIC_	process.env.NUXT_PUBLIC_XXX	서버/클라이언트 구분
SvelteKit	PUBLIC_	import.meta.env.PUBLIC_XXX	서버 변수는 PRIVATE_으로 관리

 

공통 원칙

• 서버에서만 필요한 변수(API key 등)는 접두사 없음
• 클라이언트에 노출되어야 하는 변수만 접두사 붙임
• 브라우저에서 console.log(import.meta.env) 하면 노출 범위를 직접 확인 가능

5. Git 관리와 보안

 

• .env : 기본값만 (공유 가능)
• .env.local, .env.*.local : 절대 커밋 금지 (API 키 등 민감한 정보)

# local env files
.env.local
.env.*.local

 

 

6. 실제 예시 (Vite 기준)

# .env
VITE_APP_NAME=BankLab
VITE_API_BASE_URL=https://api.banklab.kr

# .env.development
VITE_API_BASE_URL=http://localhost:8080

# .env.local
VITE_DEV_TOKEN=dev-only-token-123

console.log(import.meta.env.VITE_APP_NAME); // BankLab
console.log(import.meta.env.VITE_API_BASE_URL); // http://localhost:8080
console.log(import.meta.env.VITE_DEV_TOKEN); // dev-only-token-123

7. 자주 하는 실수 정리

실수	해결방법
.env.local 적용이 안 됨	mode가 맞는 .env.[mode].local인지 확인
API_KEY가 undefined로 나옴	접두사(VITE_, NEXT_PUBLIC_ 등) 추가
env 수정했는데 반영 안 됨	개발 서버 재시작 필요
Git에 키가 올라감	.gitignore 설정 누락 확인