API 키는 어디에 두나 — 파일·Git·Vercel 환경변수

오일기 · 한국이러닝인재개발원 원장 · 2026-09-23

API 키 = 비밀번호. 홈페이지 파일·GitHub·채팅·캡처 어디에도 안 넣습니다. 그럼 어디에? .env와 배포 설정, 그리고 새었을 때 할 일.

API 키는 다른 회사 기능(AI·지도·문자·결제)을 쓰는 열쇠입니다. 새면 내 계정으로 사용·결제가 일어날 수 있습니다. 비밀번호와 똑같이 다룹니다. 이 한 줄이 전부이고, 나머지는 "그럼 어디에 두나"입니다.

두면 안 되는 곳

홈페이지 파일(index.html 등) — 공개 페이지는 원본도 보입니다. 주소를 아는 누구나 키를 읽습니다
GitHub — 저장소가 Private이어도 넣지 않습니다. 실수로 Public이 되거나, 공유하는 순간 새어 나갑니다
채팅·캡처 — 단톡방, 스크린샷, AI 대화창. 보내기 전에 키·비밀번호가 찍혀 있지 않은지 확인
CLAUDE.md·기획.md·SKILL.md — 이 파일들도 폴더째 GitHub에 올라갑니다

두는 곳

내 컴퓨터: .env 파일. 프로젝트 폴더에 .env라는 파일을 두고 그 안에만 적습니다. 그리고 .gitignore(GitHub에 올리지 않을 파일 목록)에 .env를 적어 둡니다. 그러면 저장·올리기를 해도 이 파일은 창고에 안 갑니다. Claude에게 "이 폴더를 GitHub에 올려줘"라고 할 때 "비밀 파일은 .gitignore로 제외"를 한 줄 넣으면 알아서 합니다.

배포 서버: Vercel 환경변수. .env는 GitHub에 안 올라가니 Vercel도 모릅니다. 그래서 Vercel 프로젝트 설정 → Environment Variables에 같은 이름·값을 따로 넣습니다. "로컬에서는 되는데 배포하면 안 된다"의 흔한 원인이 여기입니다.

어디	무엇	누가 읽나
.env (내 컴퓨터)	키 원본	내 컴퓨터에서 돌 때
.gitignore	.env를 올리지 말라는 목록	Git
Vercel 환경변수	같은 키	배포 서버에서 돌 때

공개용과 비밀용은 다릅니다

일부 키는 브라우저에 보여도 되게 설계돼 있습니다(예: 데이터베이스 서비스의 공개 키). 그런 키는 이름에 "public"이 붙고, 서버 쪽에 접근 제한(RLS 같은 규칙)이 걸려 있어야 안전합니다. 이름에 "secret", "service", "private"이 들어간 키는 절대 화면에 안 갑니다. 헷갈리면 Claude에게 묻습니다. "이 키는 브라우저에 보여도 되는 키야, 서버에서만 써야 하는 키야?"

첫 서비스에서는 키가 필요 없게 만듭니다

가장 안전한 방법은 안 쓰는 것입니다. 한 페이지 계산기, 소개 홈페이지, 재고 확인표에는 키가 필요 없습니다. 만들다가 Claude가 "API 키를 넣어 주세요"라고 하면 멈추고 이렇게 말합니다. "키 없이 되는 방법으로 해줘." 키가 필요한 기능은 다음 버전으로 예약합니다.

이미 새었다면

파일에서 지우는 걸로 끝이 아닙니다. GitHub 기록에 남아 있고, 캡처는 이미 퍼졌습니다. 그 서비스에서 키를 무효화하고 새로 발급해 교체합니다. 그다음 .env와 Vercel 설정을 새 키로 바꿉니다. 순서는 무효화가 먼저입니다.

올리기 전 한 줄

Claude에게 이렇게 보내세요

올리기 전에 비밀번호·키가 든 파일이 있는지 점검해줘.
.env가 .gitignore에 있는지도 확인해줘.

이 한 줄을 습관으로 만들면 대부분의 사고가 안 납니다. 비밀번호·키는 파일·GitHub·단톡방에 두지 않습니다. 배포의 보안 한 줄입니다.

더 깊게 — 가이드 12장 · GitHub과 Vercel로 인터넷에 공개하기

4주 동안 직접 만들어 보고 싶다면클로드 바이브코딩 기초반 — 매주 화요일 3시간, 문정역 교육센터. 정원 10명, 막힌 화면을 같이 봅니다.일정·수강료 보기 →