참고
본 글은 생성형 AI를 통해 작성되었음을 알립니다.
Node.js 기반 프로젝트를 하다 보면 .env 파일을 자주 마주치게 됩니다. 환경변수를 따로 빼서 관리하는 건 이제 기본 중의 기본이죠. 그런데 .env 파일도 여러 종류가 있다는 건 알고 계셨나요? 단순히 .env 하나만 두고 사용하는 게 아니라 용도에 맞는 파일을 구분해서 관리해야 환경 설정도 명확해지고, 협업도 수월해집니다.
오늘은 프로젝트에서 필수적인 .env 파일의 종류와 각각의 쓰임새에 대해 정리해보겠습니다.
왜 .env를 사용하는가?
.env 파일은 환경변수(Environment Variables)를 관리하기 위한 파일입니다. 아래와 같은 목적에서 사용됩니다
- 비밀번호, API 키 같은 민감 정보를 코드에 노출하지 않기 위해
- 배포 환경(개발/운영 등)에 따라 설정을 다르게 하기 위해
- 협업 시 개인 설정을 분리해서 충돌을 피하기 위해
.env에 정의된 변수는 대부분 process.env로 접근할 수 있습니다.
📁 .env의 종류와 역할
1. .env(기본 환경 파일)
가장 일반적인 환경 파일로, 모든 환경에서 공통으로 적용되는 기본값을 정의합니다.
# .env
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
LOG_LEVEL=info개발, 테스트, 배포 환경 모두에서 공통으로 필요한 값은
.env파일에
2. .env.local(개인 개발용 환경 파일)
개발자의 로컬 환경에만 적용되는 설정입니다. 보통 .gitignore에 추가해서 버전 관리에 포함되지 않도록 합니다.
# .env.local
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000
DB_PASSWORD=localsecret개인 설정, 로컬 전용 비밀번호, 테스트 API 키 등을 여기에
3. .env.production(운영 환경 전용)
운영 배포 시 사용되는 설정 파일입니다.NODE_ENV=production일 때만 로드됩니다.
# .env.production
NEXT_PUBLIC_API_BASE_URL=https://prod-api.example.com
LOG_LEVEL=error실제 서비스 운영에 필요한 민감한 설정이 담깁니다. 배포 자동화 도구(Vercel, Netlify 등)에서도 자주 사용됩니다.
5. .env.test (테스트 환경 전용)
테스트 실행 시 필요한 설정을 담는 파일입니다. Jest, Playwright, Cypress 등 테스트 도구에서 NODE_ENV=test로 실행할 때 활용됩니다.
# .env.test
DB_URL=test-db-url
API_MODE=mock테스트용 데이터베이스 URL, 가짜 API 키, 테스팅 전용 플래그에 적합합니다.
⚠️ 각 .env 파일의 우선순위는?
만약 여러 개의 .env 파일에 같은 키가 정의되어 있다면, 우선순위에 따라 적용됩니다. 예를 들어 Next.js, dotenv 등 대부분의 환경에서 다음과 같은 순서로 적용됩니다:
.env.local > .env.[mode] > .env.env.local → env.development → .env 순서로 덮어씌워집니다.
✅.env 배치 팁
| 상황 | 사용해야 할 .env 파일 |
|---|---|
| 모든 환경에서 공통으로 필요한 설정 | .env |
| 팀원마다 다른 개발 설정 필요 | .env.local |
| 개발 전용 플래그 및 설정 필요 | .env.development |
| 운영 서버에 배포할 설정 | .env.production |
| 테스트 전용 설정 | .env.test |
