.env.example을 실제 .env와 함께 관리해야 하는 이유

.env 파일은 git에 올라가지 않는다. .gitignore에 들어가 있고, 당연히 그래야 한다. 그래서 새 환경을 세팅할 때 어떤 변수가 필요한지는 .env.example을 보고 파악한다. 이 파일이 실제와 달라져 있으면 배포가 조용히 깨진다.

어떻게 방치되는가

흐름은 보통 이렇다. 기능을 추가하면서 .env에 변수를 하나 추가한다. 코드는 커밋하고 배포도 한다. 그런데 .env.example 업데이트는 잊는다. 몇 달이 지나면 .env.example에는 없는 변수가 .env에 5~6개 쌓인다.

그 상태로 새 서버를 세팅하거나 다른 개발자가 클론하면 앱이 뜨긴 하는데 특정 기능이 안 된다. 로그에 에러가 없어서 원인을 찾는 데 시간이 걸린다.

.env.example 작성 원칙

값은 비워두거나 더미 값을 넣고, 어디서 얻는 값인지 주석으로 남긴다.

# .env.example

# 데이터베이스 연결 (PostgreSQL)
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# JWT 시크릿 (openssl rand -base64 32 로 생성)
JWT_SECRET=

# AWS S3 (버킷 이름과 리전은 인프라 팀에 문의)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=ap-northeast-2
AWS_S3_BUCKET=

# 외부 API
STRIPE_SECRET_KEY=sk_test_...
SENDGRID_API_KEY=

JWT_SECRET= 처럼 값을 비워두면 해당 변수가 필요하다는 것을 알 수 있고, sk_test_... 처럼 형식 힌트를 주면 실제 값을 어떻게 채워야 하는지 감을 잡을 수 있다.

동기화를 놓치지 않는 방법

.env를 바꿀 때 .env.example을 같은 커밋에 포함시키는 것이 제일 확실하다. PR 리뷰 단계에서 .env.example이 빠진 것을 잡을 수 있도록, 팀이 있다면 리뷰 체크리스트에 추가해두면 좋다.

자동화가 필요하면 dotenv-linter 같은 도구로 CI에서 .env.example에 없는 키가 코드에서 참조되는지 검사할 수도 있다. 하지만 그 전에 습관이 먼저다.

실제로 누락됐을 때 빠르게 찾는 방법

# .env에는 있고 .env.example에는 없는 키 찾기
comm -23 \
  <(grep -oP '^[A-Z_]+(?==)' .env | sort) \
  <(grep -oP '^[A-Z_]+(?==)' .env.example | sort)

이 명령이 아무것도 출력하지 않으면 두 파일의 키 목록이 일치하는 것이다. 차이가 있으면 .env.example에 추가해야 할 변수 목록이 나온다.