환경변수 (Environment Variable)

프로그램이 실행되는 '환경'마다 다르게 주입되는 변수라는 뜻이에요. 같은 코드가 내 컴퓨터에선 테스트 DB를, 배포 서버에선 실제 DB를 쓰게 만드는 장치입니다.

왜 필요한가요?#

두 가지 이유예요. 보안 — API 키를 코드에 적으면 깃허브에 올라가는 순간 유출입니다 (봇들이 공개 저장소를 실시간 스캔해서, 유출된 AWS 키는 보통 몇 분 안에 도용됩니다). 환경 분리 — 개발/배포 환경이 다른 값을 쓰려면 코드 밖에 있어야 합니다.

로컬에서는 .env 파일에 KEY=값 형태로 적고, 이 파일은 반드시 .gitignore에 넣습니다. 배포하면 플랫폼(Vercel 등)의 설정 화면에 같은 키를 등록해요 — .env 파일은 배포 서버에 따라가지 않는다는 게 초심자가 가장 많이 놓치는 부분입니다. 로컬에선 되는데 배포하면 안 되는 이유 1순위예요.

프론트엔드 노출 주의#

NEXT_PUBLIC_(Next.js), VITE_(Vite) 접두사가 붙은 변수는 브라우저에 노출됩니다. 공개돼도 되는 값(공개 API 주소 등)만 이 접두사를 쓰고, 비밀 키는 절대 붙이면 안 돼요.

AI에게 시키기#

코드에 하드코딩된 API 키를 환경변수로 옮겨줘.
- .env.local 에 키를 넣고 .gitignore 에 포함됐는지 확인
- 서버 전용 값이니 NEXT_PUBLIC_ 접두사 쓰지 말 것
- 키 이름만 적힌 .env.example 파일도 만들어줘
- 배포 시 Vercel 환경변수에 등록해야 한다는 걸 README에 한 줄 남겨줘

혼동 주의#

• .env vs .env.example: 전자는 실제 값(커밋 금지), 후자는 키 이름만 적은 견본(커밋함)
• 설정 파일(config): 공개돼도 되는 설정은 코드에 있어도 됩니다. 환경변수는 비밀이거나 환경마다 다른 값 전용