아까는 됐는데 배포하니까 안 될 때 — 환경변수
내 컴퓨터에서 테스트할 땐 분명 잘 되던 AI 기능이, 배포한 주소로 열면 안 돼요. 거의 항상 원인은 하나 — API 키(환경변수)가 서버에 안 올라갔기 때문이에요. 왜 그런지, 어떻게 넣는지 단계별로 정리합니다.
왜 아까는 됐는데 배포하면 안 될까
API 키는 비밀번호라서 .env.local이라는 비밀 파일에 넣어뒀죠. 이 파일은 보안 때문에 일부러 GitHub(코드 저장소)에도 안 올라가고, 배포할 때도 서버로 안 따라가요. 그래서 이런 일이 생겨요:
같은 사이트인데 왜 배포본만 안 될까
내 컴퓨터
.env.local에 키가 있음 → AI 잘 됨
배포된 서버
.env.local이 안 올라감 → 키 없음 → AI 안 됨
내 컴퓨터
.env.local에 키가 있음 → AI 잘 됨
배포된 서버
.env.local이 안 올라감 → 키 없음 → AI 안 됨
키는 내 컴퓨터에만 있고, 서버엔 없어서 생기는 일이에요
이게 잘못된 게 아니에요
넣는 방법은 두 가지
방법 A — 직접 클릭 (GUI)
Vercel 웹사이트에 들어가 화면에서 직접 입력. 눈으로 보고 넣으니 실수가 적어요. 확실한 방법.
방법 B — AI에게 시키기 (CLI)
Claude에게 명령어로 넣어달라고 하기. 빠르지만, 가끔 줄바꿈 문제로 잘못 들어가요(뒤에서 다룸). Windows에선 특히 조심해야 해요.
처음이라면, 그리고 Windows를 쓴다면 방법 A(직접 클릭)를 추천해요. 눈으로 확인하며 넣는 게 제일 안 틀려요.
방법 A — Vercel 화면에서 직접 넣기
프로젝트 → Settings → Environment Variables
Vercel(vercel.com)에 로그인 → 내 프로젝트 클릭 → 왼쪽 사이드바에서 Settings →Environment Variables를 엽니다.
이름(Key)과 값(Value) 입력
두 칸을 채워요. 이름은 코드에서 부르는 그 이름 그대로, 값은 실제 키를 붙여넣습니다.
Key(이름): ANTHROPIC_API_KEY
Value(값): sk-ant-... (내 실제 키)
붙여넣을 때 앞뒤 공백·줄바꿈 조심
Supabase 키 이름이 새것으로 바뀌는 중이에요
anon / service_role)에서 sb_publishable_...(공개용) /sb_secret_...(비밀용)으로 바뀌고 있어서, 화면에 둘 중 어느 쪽이든 보일 수 있어요. secret(service_role) 키는 이름 앞에 NEXT_PUBLIC_을 절대 붙이지 마세요. 붙이면 브라우저에 그대로 노출돼요.적용 범위 확인하고 저장
보통 Production·Preview·Development 전부 체크된 채로 저장하면 됩니다. (실서비스 주소는 Production이에요 — 이게 빠지면 배포본에서 또 안 돼요.) Save 클릭.
참고: 값을 Sensitive로 저장하면 저장 후엔 다시 볼 수 없어요. (Development 칸은 Sensitive를 지원하지 않아요.)
다시 배포(Redeploy)
환경변수는 다음 배포부터 적용돼요. 이미 배포된 사이트라면, Vercel의 Deployments에서 최신 배포의 Redeploy를 눌러 한 번 다시 올려야 키가 실제로 반영됩니다. 이걸 안 해서 “넣었는데 왜 안 되지?” 하는 경우가 많아요.
방법 B — Claude에게 시켜서 넣기
Vercel은 명령어(CLI)로도 환경변수를 넣을 수 있어요. 그러니 화면에 안 들어가고 Claude에게 바로 시킬 수도 있어요. 단, 먼저 한 번만 준비할 게 있어요:
Vercel CLI 설치하고 로그인 (처음 한 번)
터미널에서 아래 두 줄을 차례로 실행해요. 로그인하면 브라우저가 열리니 Vercel 계정으로 승인하면 돼요.
npm i -g vercel
vercel login이 두 개가 안 돼 있으면 Claude가 명령어를 실행해도 “vercel을 찾을 수 없다”거나 로그인 오류가 나요.
이렇게 시키기
Vercel 환경변수에 ANTHROPIC_API_KEY를 등록해줘. 값은 내 .env.local에 있는 그 키야. Production·Preview·Development 전부에 적용하고, 끝나면 다시 배포까지 해줘
Claude가 vercel env add 같은 명령으로 넣고, 재배포까지 해줍니다.
된다고 해도 — 실제로 되는지 꼭 확인
여기가 핵심이에요. Claude가 “등록했어요”라고 해도 배포된 사이트에서 AI 기능을 실제로 한 번 눌러보세요. 명령어로 넣을 땐 눈에 안 보이니, 됐다는 말만 믿지 말고 결과로 확인해야 해요.
AI가 넣었다는데 계속 안 될 때 — 줄바꿈을 의심하세요
방법 B(AI/명령어)로 넣을 때 제일 흔한 함정이에요. 키 값 끝에 눈에 안 보이는 줄바꿈(엔터)이나 공백이 딸려 들어가면, 서버는 그걸 “다른 키”로 읽어서 계속 인증이 안 돼요. Claude는 “정상 등록됐다”고 하는데 사이트는 안 되는, 답답한 상황이 이거예요.
Windows라면 더 조심하세요
echo나 PowerShell 파이프(|)로 값을 넘기면 끝에 줄바꿈이 붙기 쉬워요.Windows에선 방법 A(직접 클릭)로 넣는 걸 추천해요.이럴 때 이렇게 시키세요:
Vercel 환경변수 ANTHROPIC_API_KEY를 삭제하고, 끝에 줄바꿈이나 공백이 없는 깨끗한 값으로 다시 등록한 다음 재배포해줘. 값은 내 .env.local에서 가져오되, 끝의 줄바꿈은 빼고 넣어줘
그래도 안 되면 방법 A로 직접 다시 넣는 게제일 빨라요. Sensitive로 저장한 값은 저장 후에 다시 볼 수 없어서, ‘값을 열어서 확인’할 수가 없어요. 그러니 Vercel 화면에서 그 환경변수를 삭제하고, 깨끗하게 다시 붙여넣어서 저장한 뒤 재배포하세요.
배포하면 왜 링크가 2개씩 생겨요? — 프리뷰 vs 프로덕션
Vercel에 배포하다 보면 프리뷰(preview)와 프로덕션(production) 링크가 따로 나와서 헷갈려요. 흔한 오해부터 풀면 — 프리뷰는 ‘개발용(dev) 서버’가 아니에요.
프리뷰(preview)
코드를 저장(커밋)해 올릴 때마다 생기는 ‘그 버전 미리보기’ 링크예요. 커밋마다 주소가 달라서 “이 버전은 이랬지” 하고 확인할 때 씁니다. 남들에게 정식 공개하는 주소가 아니에요.
프로덕션(production)
최종 배포 — 내가 산 도메인이나 ○○.vercel.app 주소로 가는 진짜 서비스 주소예요. “프로덕션으로 올려” 해야 여기로 반영됩니다.
프리뷰라고 DB가 자동으로 분리되는 건 아니에요