.env 파일 생성부터 설정까지 완벽 정리

.env 파일 생성부터 설정까지 완벽 정리

📌 이 글의 핵심 요약

• .env 파일은 API 키, DB 비밀번호 등 민감한 값을 코드 밖에서 관리하는 파일이다
• 프로젝트 루트에 생성하고 .gitignore에 추가하는 것이 기본 원칙
• Node.js에서는 dotenv 패키지로, Next.js·Vite는 빌트인으로 읽어온다
• .env.example 파일을 함께 올려 팀원 온보딩을 간소화할 수 있다

📋 목차

1. .env 파일이 필요한 이유
2. .env 파일 생성과 기본 문법
3. Node.js에서 dotenv로 읽어오기
4. 프레임워크별 .env 설정 방식
5. 보안 관리와 실전 팁
6. 정리 및 결론

.env 파일이 필요한 이유

개발을 처음 시작하면 API 키나 데이터베이스 비밀번호를 코드에 직접 적는 경우가 많다. 빠르게 테스트하기엔 편하지만, 그 코드를 GitHub에 올리는 순간 전 세계에 공개된다. 실제로 AWS 키가 노출돼 수백만 원의 요금이 청구된 사례가 꾸준히 보고된다.

.env 파일은 이 문제를 방지하기 위한 표준 방식이다. 민감한 값을 코드와 분리해 별도 파일에 보관하고, 해당 파일은 Git 추적에서 제외한다. 로컬 개발 환경과 배포 서버에 각각 다른 값을 적용할 수 있어 환경별 설정 분리에도 쓰인다.

---

.env 파일 생성과 기본 문법

파일 이름은 정확히 .env다. 확장자 없이 점으로 시작하는 숨김 파일 형태로, 프로젝트 최상단 루트 디렉터리에 위치시킨다. VS Code나 터미널에서 직접 생성하면 된다.

# 데이터베이스 설정 DB_HOST=localhost DB_PORT=5432 DB_NAME=myapp DB_PASSWORD=supersecret # API 키 RESEND_API_KEY=re_xxxxxxxxxx OPENAI_API_KEY=sk-xxxxxxxxxx # 앱 설정 NODE_ENV=development PORT=3000

📝 .env 문법 규칙

• 키=값 형태로 한 줄에 하나씩 작성
• 값에 공백이 있으면 따옴표로 감싼다 — APP_NAME="My App"
• #으로 시작하는 줄은 주석으로 처리된다
• 키 이름은 대문자와 언더스코어 조합이 관례
• 등호(=) 앞뒤에 공백을 넣지 않는다

---

Node.js에서 dotenv로 읽어오기

.env 파일은 그 자체로 동작하지 않는다. 런타임에서 이 파일을 읽어 환경변수로 주입해주는 도구가 필요하다. Node.js에서는 dotenv 패키지가 사실상 표준이다.

# 설치 npm install dotenv

설치 후 애플리케이션 진입점 파일 최상단에 아래 한 줄을 추가하면 된다.

require('dotenv').config(); // 이후 어디서든 process.env로 접근 가능 const apiKey = process.env.RESEND_API_KEY; const port = process.env.PORT || 3000;

💡 ES Module 환경에서 사용할 때

package.json에 "type": "module"이 있거나 .mjs 파일을 쓴다면 require 대신 import 구문을 써야 한다. import 'dotenv/config' 한 줄로 동일하게 동작한다.

---

프레임워크별 .env 설정 방식

Next.js, Vite, Create React App 같은 프레임워크는 dotenv 없이도 .env 파일을 자동으로 읽는다. 단, 브라우저에 노출되는 값과 서버에서만 쓰는 값을 접두어로 구분한다는 점이 중요하다.

🔧 프레임워크별 환경변수 접두어 규칙

• Next.js — 브라우저 노출: NEXT_PUBLIC_ 접두어 필수. 없으면 서버 전용
• Vite — 브라우저 노출: VITE_ 접두어 필수
• CRA — 브라우저 노출: REACT_APP_ 접두어 필수
• 순수 Node.js — dotenv 로드 후 모두 서버 전용으로 사용

API 키처럼 외부에 노출되면 안 되는 값은 절대 브라우저 노출 접두어를 붙이면 안 된다. 접두어를 잘못 붙이면 빌드된 JS 파일 안에 그대로 포함돼 누구나 확인할 수 있는 상태가 된다.

---

보안 관리와 실전 팁

⚠️ 반드시 .gitignore에 추가할 것
.env 파일을 Git에 올리는 실수는 생각보다 자주 발생한다. 프로젝트 생성 직후 .gitignore 파일에 .env와 .env.local을 추가하는 것을 습관으로 만들어야 한다. 이미 올라간 경우에는 git rm --cached .env 명령으로 추적을 제거해야 한다.

.env.example 파일 활용

팀 프로젝트에서는 실제 값 대신 키 이름과 설명만 담은 .env.example 파일을 Git에 올려두는 방식을 쓴다. 새로운 팀원이 합류하면 이 파일을 복사해 실제 값을 채우기만 하면 된다.

# .env.example (Git에 올리는 파일) DB_HOST= DB_PASSWORD= RESEND_API_KEY= OPENAI_API_KEY=

환경별로 .env.development, .env.production처럼 분리하는 방식도 실무에서 자주 쓰인다. 개발 서버와 운영 서버에 다른 DB나 API 키를 쓸 때 파일 단위로 관리하면 혼선이 줄어든다.

---

정리 및 결론

.env 파일 핵심 정리

• 프로젝트 루트에 .env 파일 생성, 키=값 형식으로 민감한 값 분리 저장
• 생성 즉시 .gitignore에 추가 — GitHub 노출 방지 필수
• Node.js는 dotenv 패키지, Next.js·Vite는 빌트인으로 자동 로드
• 브라우저 노출 여부는 프레임워크별 접두어 규칙으로 제어
• .env.example을 Git에 올려 팀원 온보딩 비용을 줄인다

.env 파일 하나를 제대로 관리하는 것만으로도 보안 사고의 상당 부분을 예방할 수 있다. 처음 프로젝트를 세팅할 때 이 흐름을 체크리스트로 만들어두면 나중에 실수할 일이 줄어든다.