로컬은 되는데 Vercel 배포만 실패할 때 체크리스트

이런 증상이라면

로컬에서는 멀쩡히 도는데 Vercel 배포에서만 빌드가 깨지거나, 배포된 사이트에서만 특정 기능이 안 됩니다.

🔎 이 문제는 대부분 코드가 아니라 대시보드·설정에 있습니다. AI에게 코드를 고쳐달라고 반복해도 안 풀리는 이유예요.

흔한 원인 (가능성 순)

1환경변수 차이환경변수

로컬 .env.local의 값이 Vercel에 없습니다. 빌드 시 필요한 값이 없으면 빌드가, 런타임에 필요하면 페이지가 깨집니다.

2파일명 대소문자코드

맥/윈도우는 대소문자를 구분하지 않지만 Vercel(리눅스)은 구분합니다. import "./Button" vs 실제 파일 button.tsx면 로컬만 통과합니다.

3Node 버전 / 빌드 설정 차이대시보드

로컬 Node 버전과 Vercel 설정이 다르면 특정 문법/패키지가 배포에서만 실패할 수 있습니다.

빌드 로그를 봐도 뭘 봐야 할지 모르겠어요.

빨간 첫 번째 에러 줄과 그 위 몇 줄이 핵심입니다. "Module not found", "is not defined", "Cannot read" 같은 키워드로 원인이 갈립니다.

위를 다 해봤는데도, 또는 AI(Cursor·Claude)한테 물어봐도 계속 같은 에러라면 — 에러 로그를 붙여넣으면 60초 안에 진짜 원인을 짚어드려요.