[초급] 당신의 API 키가 인터넷에 떠돌아다니기 직전인 이유 (Netlify .env 삽질기)

결론부터 말하자면, .env 파일은 당신 컴퓨터에서만 유효하다.

Netlify 배포 서버는 당신의 .env 파일을 알지도 못하고, 알고 싶어하지도 않음. 이게 핵심이다. ‘내 컴퓨터에서는 잘 됐는데 왜 배포만 하면 터지지?’ 같은 소리를 하는 건, 집 열쇠로 회사 문을 열려는 것과 같은 행동이다. 당연히 안 열린다.

🔥 `.env` 파일의 본질: 이 파일은 Git 추적에서 의도적으로 제외된다. `.gitignore` 파일에 `/node_modules`와 함께 최상단에 박혀 있는 이유다. API 키 같은 민감 정보를 Git 저장소에 올리는 바보짓을 막기 위한 최소한의 안전장치인 셈.

엔지니어링 관점에서 본 메커니즘 ⚙️

당신이 `git push` 명령을 날리면, 코드는 Git 저장소(Github 등)로 전송된다. Netlify는 이 저장소의 코드를 가져와서 빌드(Build)라는 과정을 거친다. 포장해서 제품으로 만드는 과정이다. 이때 `.gitignore`에 등록된 파일들은 애초에 저장소에 올라가지 않았으니, Netlify 빌드 서버에는 존재하지 않는다. 당연히 빌드 과정에서 `process.env.API_KEY` 같은 코드는 값을 찾지 못하고 `undefined`를 뱉으며 터져버린다. 이건 버그가 아니라, 그렇게 설계된 거다.

직관적인 비유: 개인 지갑과 법인 카드

`.env` 파일은 당신의 개인 지갑이다. 현금, 비밀번호 적은 쪽지 등 나만 아는 것들이 들어있다. 이걸 통째로 회사에 제출하지는 않는다.
Netlify 환경변수는 회사의 법인 카드다. 회사(Netlify)가 업무에 필요한 경비(API 키)를 쓸 수 있도록, 정식 절차를 밟아 발급해주는 거다. 개인 지갑을 뒤지는 게 아니라.

그럼 어떻게 해야 하는가: Netlify UI에 직접 박아라

정답은 간단하다. Netlify 대시보드에 직접 환경변수를 등록하면 끝남.

등록 경로

Site settings > Build & deploy > Environment > Environment variables

여기에 `Key`와 `Value`를 직접 입력하면 된다. 예를 들어, `.env` 파일에 `REACT_APP_API_KEY=12345`라고 적었다면, Netlify UI에는 Key에 `REACT_APP_API_KEY`를, Value에 `12345`를 입력한다. 간단하다.

직장인 열에 아홉은 여기서 막힌다 (흔한 실수 3가지)

이론은 쉽다. 하지만 실전에서는 꼭 엉뚱한 곳에서 헤맨다. 나도 그랬다.

❌ 실수 1: 프레임워크별 접두사(Prefix) 누락

상황: ‘분명 Netlify에 변수 등록했는데 왜 자꾸 undefined가 뜨지?’
원인: Create React App, Vite 같은 최신 프레임워크들은 보안상의 이유로 특정 접두사가 붙은 환경변수만 코드 안에서 읽을 수 있도록 제한한다. 예를 들어 Create React App은 `REACT_APP_`, Vite는 `VITE_`가 붙어야 한다.
해결책: `.env` 파일에 `API_KEY=12345`라고 썼다면 틀렸다. `REACT_APP_API_KEY=12345`라고 써야 로컬에서 돌아간다. 그리고 Netlify에도 똑같이 `REACT_APP_API_KEY`라는 이름으로 등록해야 한다. 당신이 쓰는 프레임워크 공식 문서를 확인하는 게 가장 빠르다.

❌ 실수 2: `.env.production` 파일을 Git에 커밋하는 만행

상황: ‘로컬용은 .env, 배포용은 .env.production에 넣고 커밋하면 되겠지?’
원인: 이건 그냥 API 키를 전 세계에 공개하는 행위다. `.gitignore`의 존재 이유를 정면으로 무시하는 것. 악의적인 봇들이 Github을 상시 스캔하며 이런 키들을 수집하고 있다는 사실을 기억해야 한다. 순식간에 요금 폭탄을 맞을 수 있다.
해결책: `.env`로 시작하는 모든 파일은 `.gitignore`에 포함시켜 절대 Git 저장소에 올라가지 않도록 한다. 운영(Production) 환경에서 필요한 모든 변수는 오직 Netlify UI를 통해서만 관리한다. 이게 철칙이다.

❌ 실수 3: 빌드 컨텍스트(Context)를 이해하지 못함

상황: ‘분명 변수를 등록했는데 왜 브랜치 배포에서는 안되고 메인 배포에서만 되지?’
원인: Netlify는 `production`, `deploy-preview`, `branch-deploy` 등 다양한 빌드 컨텍스트를 제공한다. 변수를 등록할 때 특정 컨텍스트에서만 작동하도록 설정할 수 있다. 기본값은 ‘All scopes’지만, 이걸 잘못 건드리면 특정 환경에서만 변수가 누락되는 현상이 발생한다.
해결책: 웬만하면 ‘All scopes’로 두고 쓰는 게 정신건강에 이롭다. 만약 개발/운영 환경의 API 키를 다르게 써야 하는 고급 케이스라면, 그때 컨텍스트 개념을 정확히 파고들어서 분리한다. 초급 단계에서는 그냥 하나로 통일하면 된다.

핵심 한 줄 요약 📌

로컬 개발은 `.env` 파일, 서버 배포는 Netlify UI. 이 둘을 명확히 분리해서 사용하면 된다. 이것만 기억하면 된다.

PipeMaster-Lab 운영정책 및 제보 안내