[Nextjs] 환경 변수(.env) 안전하게 관리하기

깃허브에 올라간 API Key는 더 이상 비밀이 아니다
개발을 시작할 때 가장 흔히 하는 실수 중 하나가 API 키나 인증 토큰이 담긴 .env 파일을 그대로 GitHub에 올리는 것이다.
한 번 공개된 키는 삭제하더라도 커밋 히스토리에 남아 언제든 악용될 수 있다.
오늘은 Next.js에서 환경 변수를 안전하게 관리하고 사용하는 전략을 정리해 보았다.

NEXTPUBLIC: 노출과 은닉의 경계선

• Next.js는 환경 변수의 이름에 따라 클라이언트 노출 여부를 결정하는 강력한 규칙이 있다.
• NEXT_PUBLIC_ 접두사가 있는 경우
  • 브라우저(클라이언트 사이드)에서 접근 가능하다.
  • GA4 측정 ID나 공개 API 주소 등에 사용한다.
• NEXT_PUBLIC_ 접두사가 없는 경우
  • 오직 서버 사이드(Node.js 환경)에서만 접근 가능하다.
  • DB 비밀번호, Sentry 인증 토큰, 결제 비밀키 등이 이에 해당한다.

.env 파일의 우선순위와 관리 전략

.env.local을 깃허브에 올리는 것은 집 비밀번호를 대문에 적어두는 것과 같다.

• Next.js는 실행 환경에 따라 여러 개의 .env 파일을 인식한다.
• .env.local: 로컬 개발용. 반드시 .gitignore에 추가하여 개인 자산으로 관리해야 한다.
• .env.production: 배포 환경에서 사용할 기본값들을 정의한다.
• .env.development: 개발 환경용 기본 설정값들을 정의한다.

배포 환경(Vercel, AWS 등)에서의 주입

• 실제 서비스 배포 단계에서는 파일을 올리는 대신, 배포 플랫폼의 대시보드에서 환경 변수를 직접 주입한다.
• 가령 에러로깅을 위한 SENTRY를 연동할때 SENTRY_AUTH_TOKEN 역시 Vercel의 Environment Variables 설정에서 관리함으로써 코드 상에는 흔적을 남기지 않고 빌드 과정에서만 안전하게 사용되도록 구성했다.

유효성 검사: 타입 세이프(Type-safe)한 환경 변수

• 단순히 process.env를 사용하는 것을 넘어, Zod나 Envalid 같은 라이브러리를 활용하면 환경 변수가 누락되었을 때 빌드 단계에서 미리 에러를 잡아낼 수 있다.
• 이는 런타임에 갑자기 서비스가 죽는 불상사를 막아주는 훌륭한 안전장치가 된다.

환경 변수 관리는 단순한 세팅을 넘어 프로젝트의 보안 설계 그 자체다.
현재까지의 배운 가장 큰 교훈은 "편리함보다 안전함이 우선"이라는 점이다.