📘 Kakao API + Vercel 환경변수 트러블슈팅 정리

1️⃣ 문제 상황

카카오 API (공유 / 로그인) 사용 시 아래와 같은 오류 발생

❗ 대표 에러

• 4011: 잘못된 앱 키
• 4019: 허용되지 않은 도메인
• SDK 초기화 안됨

2️⃣ 핵심 원인

🔥 가장 중요한 원인

👉 Vercel에 환경변수를 등록하지 않음

📊 실제 동작 흐름

.env.local (로컬)
→ 정상 작동

Vercel (배포)
→ env 없음
→ import.meta.env = undefined
→ Kakao.init(undefined)
→ 인증 실패 (4011)

3️⃣ 환경변수 구조 이해

📁 .env.local (로컬 환경)

• 로컬 개발 전용
• Git에 포함되지 않음

VITE_KAKAO_JAVASCRIPT_KEY=카카오JS키

☁️ Vercel Environment Variables (배포 환경)

• 배포 서버에서 사용하는 변수
• 반드시 따로 등록해야 함

👉 위치

Vercel → Settings → Environment Variables

4️⃣ 해결 방법

✅ 1. Vercel에 환경변수 등록

• Name

    VITE_KAKAO_JAVASCRIPT_KEY
  

• Value

    카카오 JavaScript 키
  

• Environment

  • ✔ Production

✅ 2. 재배포 (필수)

👉 Vercel → Deployments → Redeploy

❗ 왜 재배포해야 하나?

👉 Vite는 빌드 시점에 env를 코드에 삽입함

env 변경 → 재배포 안 하면 반영 안 됨

✅ 3. 코드 확인

const kakaoJsKey = import.meta.env.VITE_KAKAO_JAVASCRIPT_KEY;

window.Kakao.init(kakaoJsKey);

5️⃣ 카카오 API 사용 시 필수 체크

🔑 1. 키 종류

• 웹 → JavaScript 키
• 네이티브 앱 → Native App Key

🌐 2. 도메인 등록

👉 Kakao Developers

• JavaScript SDK 도메인

    https://breadbti.vercel.app
  

• 제품 링크 관리

    https://breadbti.vercel.app
  

🔁 3. Redirect URI (로그인 시)

https://breadbti.vercel.app/auth/kakao/callback

👉 코드와 완전히 동일해야 함

6️⃣ 디버깅 방법

console.log(import.meta.env.VITE_KAKAO_JAVASCRIPT_KEY);
console.log(window.Kakao?.isInitialized?.());
console.log(window.location.origin);

✅ 정상 상태

• env 값 존재 ✔
• initialized → true ✔
• origin → 등록 도메인과 동일 ✔

7️⃣ 자주 하는 실수

• env를 .env.local에만 넣고 Vercel에 등록 안 함
• env 이름 mismatch (JS_KEY vs JAVASCRIPT_KEY)
• 재배포 안 함
• Default 키 사용
• 네이티브 키 사용 (웹에서)
• 도메인 / Redirect URI 불일치

🎯 최종 정리

👉 카카오 API 오류의 대부분은

“키 문제”가 아니라 “환경변수 + 배포 문제”

💥 한 줄 핵심

👉 로컬 env ≠ Vercel env (완전히 별개)

👉 env 변경 시 반드시 재배포