환경변수 이름을 대충 지으면 나중에 생기는 혼란

혼자 개발할 때 환경변수 이름을 즉흥적으로 짓는 건 나쁜 습관이다. 처음엔 별것 아닌 것 같은데, 프로젝트가 커지고 서비스가 늘어나면 .env 파일을 열 때마다 "이게 뭐였지?"를 반복하게 된다.

흔히 생기는 혼란들

같은 것을 다르게 부르는 경우. 어떤 서비스는 DB_URL, 다른 서비스는 DATABASE_URL, 또 다른 곳은 POSTGRES_CONNECTION_STRING. 이 셋이 모두 DB 연결 문자열이면 통일하는 게 낫다. ORM마다 기본값이 다르긴 하지만(Prisma는 DATABASE_URL을 기본값으로 읽는다), 적어도 프로젝트 내에서는 일관성을 유지해야 한다.

역할이 불분명한 이름. SECRET이라는 변수가 있다면 JWT 시크릿인지, 암호화 키인지, API 시크릿인지 알 수가 없다. JWT_SECRET, ENCRYPTION_KEY, STRIPE_SECRET_KEY처럼 용도가 이름에서 드러나야 한다.

프레임워크 규칙을 모르고 이름 짓는 경우. Next.js에서 브라우저에서 접근해야 하는 값은 NEXT_PUBLIC_ 접두사가 붙어야 한다. NEXT_PUBLIC_가 빠진 API URL을 클라이언트에서 참조하면 undefined가 되는데, 왜인지 찾는 데 시간이 걸린다.

이름 짓는 원칙

몇 가지 규칙만 정해두면 나중에 편하다.

1. SCREAMING_SNAKE_CASE — 환경변수는 관례적으로 대문자 + 언더스코어를 쓴다.
2. 서비스 접두사 — 외부 서비스 관련 변수는 STRIPE_, SENDGRID_, AWS_처럼 서비스 이름을 앞에 붙인다.
3. 동사보다 명사 — ENABLE_CACHE보다 CACHE_ENABLED가 더 자연스럽게 그룹핑된다.
4. 의미 없는 약어 피하기 — AUTH_SK보다 AUTH_SECRET_KEY가 낫다. 길더라도 읽히는 게 중요하다.

.env.example을 반드시 관리한다

.env는 git에 올리지 않지만 .env.example은 올려야 한다. 빈 값으로 구조만 남겨두면 새 환경에 배포할 때 어떤 변수가 필요한지 바로 알 수 있다.

# .env.example
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
JWT_SECRET=your-secret-here
NEXT_PUBLIC_API_URL=https://api.example.com
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

주석도 짧게 달아두면 좋다. 특히 값의 형식이나 어디서 발급받는지를 적어두면 온보딩 때 쓸모 있다.

PORT 같은 흔한 이름은 충돌에 주의

PORT는 OS 레벨이나 여러 도구가 이미 사용하는 이름이다. Node.js 앱에서 process.env.PORT를 읽으면 대부분의 경우 Heroku, Railway, Fly.io 같은 플랫폼이 주입한 값을 그대로 쓸 수 있어서 편리하지만, 여러 서비스를 동시에 띄우는 환경에서는 이름 충돌이 날 수 있다. APP_PORT, API_PORT처럼 구체적으로 쓰는 게 안전하다.