[Next.js] Next.js의 환경 변수 파일 우선순위와 용도

 

1. 환경변수 로드 순서 : 우선순위 (높음 -> 낮음)

1. 시스템 환경 변수
2. .env.$(NODE_ENV).local
3. .env.local (.env.test.local 제외)
4. .env.$(NODE_ENV)
5. .env

 

$(NODE_ENV)는

npm run dev

npm run build / npm run start

npm test 에 따라 자동으로 할당되는 값이며

 

일반적으로 development, production, test 세가지 값을 가질 수 있습니다.

 

그래서 

# 개발 환경에서 실행 시 우선순위
1. .env.development.local
2. .env.local
3. .env.development
4. .env

# 프로덕션 환경에서 실행 시 우선순위
1. .env.production.local
2. .env.local
3. .env.production
4. .env

 

이런 순서로 실행이 됩니다

---

 

2. 환경변수 파일별특징

1) .env.local

• 가장 높은 우선순위의 로컬 오버라이드
• 로컬 환경에서만 사용되는 값
• git에 커밋되지 않아야 함 (보통 .gitignore에 포함)
• 개인적인 환경 설정이나 시크릿 키 저장에 적합
• 테스트(NODE_ENV=test)에서는 무시됨

 

2) .env.development

• 개발 환경(npm run dev)에서만 사용
• 팀원들과 공유해야 하는 개발 환경 설정

 

3) .env.production

• 프로덕션 환경(npm run build, npm run start)에서만 사용
• 실제 서비스에 필요한 환경 설정

 

4) .env.test

• 테스트 환경 전용
• .env.local 무시 (테스트 재현성)
• Vitest, Cypress 등 테스트 도구에서 사용

5) .env

• 모든 환경의 공통 기본값
• git에 커밋 가능
• 가장 낮은 우선순위

---

 

3. 환경 변수 접두사 규칙

NEXT_PUBLIC_ 접두사가 있는 경우

• 클라이언트와 서버 모두 접근 가능
• 빌드 시 실제 값으로 대체됨
• 공개해도 괜찮은 값에만 사용

NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_GA_ID=GA123456

 

주의 !!     = 뒤에는 따옴표가 없습니다

 

 

NEXT_PUBLIC_ 접두사가 없는 경우

• 서버 사이드에서만 접근 가능
• 클라이언트에서 접근 불가
• 보안이 중요한 값에 사용

DATABASE_URL=postgresql://...
API_SECRET_KEY=xxx

---

 

4. 환경 변수 접근 방법

 

서버 컴포넌트에서

// 모든 환경 변수 접근 가능
console.log(process.env.DATABASE_URL)
console.log(process.env.NEXT_PUBLIC_API_URL)

 

클라이언트 컴포넌트에서

// NEXT_PUBLIC_ 접두사 있는 변수만 접근 가능
console.log(process.env.NEXT_PUBLIC_API_URL)

 

 

5.  .gitignore 설정

# 로컬 환경 변수
.env*.local

# 버전 관리에서 제외할 환경 변수 파일
.env
.env.development
.env.test
.env.production