.env 파일 적용 순서 이해하기 (feat. NextJS)

일반적인 .env 파일 구조

대부분의 프로젝트에서는 다양한 환경에 맞춰 여러 .env 파일을 사용한다.

• .env: 모든 환경에서 공통으로 사용하는 기본 환경 변수
• .env.local: 로컬 개발 환경에서만 사용 (버전 관리에서 제외)
• .env.development: 개발 환경에서 사용
• .env.development.local: 개발 환경의 로컬 설정 (버전 관리에서 제외)
• .env.production: 프로덕션 환경에서 사용
• .env.production.local: 프로덕션 환경의 로컬 설정 (버전 관리에서 제외)
• .env.test: 테스트 환경에서 사용

.local 접미사가 붙은 파일들은 개발자 개인의 설정을 저장하며, 버전 관리에서 제외하는 것이 일반적이다.

일반적인 우선순위

일반적으로 환경 변수는 다음 순서로 적용된다. (프레임워크나 라이브러리에 따라 달라질 수 있음)

1. OS 환경 변수
2. .env.[환경].local
3. .env.[환경]
4. .env.local
5. .env

Next.js에서의 환경 변수 로드 우선순위

Next.js는 환경 변수를 로드할 때 다음과 같은 명확한 우선순위를 따른다.

1. .env.local: 최우선 순위
2. .env.[MODE].local: 특정 환경의 로컬 설정
3. .env.[MODE]: 특정 환경 설정
4. .env: 기본 설정

Next.js의 MODE 값

Next.js에서 [MODE]에 들어갈 수 있는 값:

• production: next start 또는 next build 실행 시 자동 지정
• development: next dev 실행 시 자동 지정
• test: next test 실행 시 자동 지정

특정 환경 파일 강제 지정하기

Next.js에서 빌드 시 production이 아닌 다른 환경의 변수를 사용하고 싶다면, env-cmd 라이브러리를 활용할 수 있다.

# env-cmd 설치
npm install env-cmd --save-dev

// package.json
"scripts": {
  "build:dev": "env-cmd -f .env.development.local next build"
}

# 실행
yarn build:dev

이 방법은 다음과 같은 상황에서 사용할 수 있다.

• 스테이징 환경을 위한 빌드 생성
• 개발 환경 설정으로 테스트 빌드 수행
• 특정 환경 변수로 로컬 테스트

주의사항

공통 주의사항

• .local 파일들은 .gitignore에 추가하여 버전 관리에서 제외
• 동일한 변수명이 여러 파일에 있을 경우, 우선순위에 따라 값이 결정됨
• 민감한 정보는 반드시 .local 파일에 저장

Next.js 특정 주의사항

• 브라우저에 노출되어야 하는 환경 변수는 NEXT_PUBLIC_ 접두사 필요
• .env.test 파일은 테스트 실행 시에만 로드됨
• 런타임에 환경 변수를 변경할 수 없음 (빌드 시점에 결정)

이렇게 환경 변수 파일의 우선순위를 이해하면서, 프로젝트 상황에 맞게 각 환경에 필요한 설정을 효과적으로 관리해보자.