④ 환경변수와 시크릿 — 키 털리지 않는 습관

왜 이게 중요한가

API 키가 GitHub 공개 레포에 올라가면 수 분 내에 봇이 긁어갑니다. 최악의 경우 Claude·OpenAI 계정에 수백 달러 청구되는 일이 실제로 자주 일어납니다. 배포 전에 이 한 편만은 꼭 짚고 가세요.

1. 기본 3원칙

1. 키는 코드에 적지 않는다 — .env 파일에만
2. .env는 절대 Git에 넣지 않는다 — .gitignore에 .env*.local 추가
3. 프로덕션 키는 플랫폼(Vercel/Netlify/CF)에만 넣는다 — 로컬에도 복사하지 말 것

2. .env 파일 구조 (Next.js 기준)

# .env.local        → 로컬 개발용, git 무시
# .env.production   → 프로덕션(참고용, 보통 플랫폼 UI로 관리)
# .env.example      → 키 이름만 적어 팀원 공유 (값은 빈칸)

.env.example 예시:

ANTHROPIC_API_KEY=
NEXT_PUBLIC_SITE_URL=
SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=

.gitignore 에 포함해야 할 항목:

.env
.env.local
.env.*.local

3. 클라이언트 vs 서버 변수 — Next.js에서 가장 자주 혼동

• NEXT_PUBLIC_* 접두사 → 브라우저로 번들됩니다. 여기 비밀키 넣으면 끝.
• 접두사 없는 변수 → 서버 런타임에서만 접근 가능

절대 NEXT_PUBLIC_ 에 넣으면 안 되는 것들

• Anthropic / OpenAI API Key
• Supabase service_role Key
• DB 비밀번호
• 결제 웹훅 시크릿

NEXT_PUBLIC_ 에 넣어도 되는 것들

• 공개 API endpoint URL
• Supabase anon Key (공개용)
• Google Analytics ID

4. 플랫폼별 환경변수 관리

Vercel

• Settings → Environment Variables
• 각 변수에 Production / Preview / Development 체크
• 수정 후 반드시 Redeploy (기존 배포엔 반영 안 됨)

Netlify

• Site configuration → Environment variables
• Scopes로 Deploy previews에서 제외 가능

Cloudflare Pages

• Settings → Environment variables
• Production / Preview 분리
• Encrypted 옵션으로 저장

5. 실수로 키를 커밋했다면 — 복구 순서

⚠ 최우선: 키를 즉시 무효화(revoke)하고 새로 발급. git rm + commit 만으론 이미 유출된 것.

1. 해당 서비스 콘솔에서 키를 revoke (Anthropic, OpenAI, Supabase 각각)
2. 새 키 발급 후 플랫폼 환경변수에 교체
3. 커밋 히스토리에서도 제거하려면:

   git filter-repo --path .env --invert-paths
   git push --force-with-lease
   

   (팀 레포면 팀원과 먼저 상의)
4. GitHub Secret Scanning 알림이 왔는지 확인 (공개 레포면 자동 경고)

6. 반복적으로 돌릴 가드

Pre-commit 훅 — gitleaks 같은 도구로 시크릿 패턴 탐지:

brew install gitleaks
gitleaks detect --source . -v

CI 단계에서도 같은 검사:

# .github/workflows/secret-scan.yml
- uses: gitleaks/gitleaks-action@v2

7. 키 로테이션 루틴

• 분기 1회 정도로 API 키를 교체
• 팀원 퇴사 시 관련 키 즉시 교체
• 각 서비스에 키별 이름/용도 적어두기 ("vercel-prod", "local-dev-andy")

8. 빠르게 점검할 수 있는 체크리스트 10개

• [ ] .env가 .gitignore에 들어가 있다
• [ ] .env.example은 있고 실제 값은 비어 있다
• [ ] NEXT_PUBLIC_ 으로 시작하는 키에 비밀값이 없다
• [ ] 프로덕션 키는 로컬 .env.local에 없다
• [ ] 플랫폼 환경변수에 Production/Preview/Development가 정확히 구분돼 있다
• [ ] 최근 30일 내 API 키가 로그에 평문으로 찍힌 적 없다
• [ ] 공개 레포라면 GitHub Secret Scanning이 켜져 있다
• [ ] pre-commit 또는 CI에 시크릿 스캔이 있다
• [ ] 팀원 이탈 후 키 교체 프로세스가 문서화돼 있다
• [ ] 마지막 로테이션 날짜를 기록해두고 있다

배포하는 법 시리즈 4편 끝. 이제 코드만 쓰면 되는 게 아니라 "올리고, 지키는 법"까지 갖췄습니다. 🎉