Vercel·Next.js 배포 오류 해결 체크리스트: 로컬에서는 되는데 배포가 안 될 때
로컬에서는 정상인데 Vercel 배포에서만 실패하는 Next.js 앱의 빌드 오류, 환경 변수, 대소문자 import, 정적 export 문제를 점검하는 순서를 정리했습니다.
"로컬에서는 잘 되는데 Vercel에 배포하면 실패합니다."
AI 코딩이나 바이브코딩으로 만든 Next.js 프로젝트에서 가장 자주 만나는 문제입니다. 개발 모드에서는 페이지가 열리고 버튼도 동작하는데, 배포 버튼을 누르는 순간 빌드가 실패하거나 특정 페이지가 404, 500으로 떨어집니다.
이때 바로 코드를 크게 바꾸면 문제가 더 꼬일 수 있습니다. 배포 오류는 코드 로직보다 환경, 설정, 빌드 타이밍에서 시작되는 경우가 많기 때문입니다. 먼저 어디서 깨지는지 확인해야 합니다.
1. 배포 로그에서 첫 번째 에러를 찾기
Vercel 배포 오류를 볼 때 가장 중요한 것은 마지막 줄이 아니라 첫 번째 의미 있는 에러입니다. 로그 아래쪽에는 같은 에러가 연쇄적으로 반복되거나, 빌드가 중단되었다는 결과만 남는 경우가 많습니다.
먼저 다음 표현을 찾으세요.
- Module not found
- Type error
- ReferenceError
- Environment Variable
- Failed to compile
- Static worker exited
- Export encountered errors
AI에게 물어볼 때도 전체 로그를 붙여넣기보다 "첫 번째 에러가 이 부분"이라고 표시해주면 정확도가 올라갑니다. 그래도 세 번 이상 같은 수정이 반복된다면 원인 진단 자체가 틀렸을 가능성이 높습니다.
2. 환경 변수 누락 확인
로컬에서는 .env 파일이 있지만 Vercel에는 그 값이 자동으로 올라가지 않습니다. Supabase, Firebase, Toss Payments, Stripe, 이메일 발송 API처럼 외부 서비스를 쓰는 프로젝트라면 환경 변수 누락이 가장 흔한 원인입니다.
확인할 것:
- 로컬 .env에 있는 키가 Vercel Project Settings에도 등록되어 있는가
- Production, Preview, Development 환경 중 필요한 범위에 모두 등록되어 있는가
- NEXT_PUBLIC_ 접두사가 필요한 값과 서버에서만 써야 하는 값을 구분했는가
- 값을 수정한 뒤 재배포를 했는가
환경 변수 문제는 에러 메시지가 모호하게 나옵니다. Cannot read properties of undefined 같은 에러가 보인다면 코드보다 환경 변수를 먼저 의심해보는 편이 빠릅니다.
3. 파일 경로 대소문자 확인
macOS에서는 파일명 대소문자를 느슨하게 처리하는 경우가 많지만, Vercel의 빌드 환경은 대소문자에 더 엄격합니다.
예를 들어 실제 파일은 components/Header.tsx인데 import에서 components/header라고 쓰면 로컬에서는 넘어가도 배포에서 실패할 수 있습니다. AI가 파일을 만들고 옮기는 과정에서 이런 문제가 자주 생깁니다.
확인할 것:
- import 경로와 실제 파일명의 대소문자가 완전히 같은가
- 폴더명을 Components와 components처럼 섞어 쓰지 않았는가
- Git에 파일명 변경이 정확히 반영되었는가
특히 Cursor나 Lovable에서 파일을 여러 번 생성했다면 이 부분을 꼭 확인해야 합니다.
4. 빌드 타임에 브라우저 객체를 쓰는지 확인
Next.js는 빌드 중에도 일부 코드를 실행합니다. 그래서 window, document, localStorage 같은 브라우저 전용 객체를 서버나 빌드 타임에서 사용하면 배포 빌드가 실패할 수 있습니다.
로컬 개발 모드에서는 괜찮아 보이지만 npm run build에서만 터지는 대표적인 패턴입니다.
확인할 것:
- window나 document를 컴포넌트 최상단에서 바로 사용하지 않았는가
- localStorage를 useEffect 밖에서 읽지 않았는가
- 클라이언트 컴포넌트가 필요한 파일에 use client가 빠지지 않았는가
- 서버 컴포넌트에서 브라우저 전용 라이브러리를 import하지 않았는가
AI가 UI를 빠르게 만들 때 자주 놓치는 부분입니다.
5. 정적 export 설정과 동적 기능 충돌 확인
Next.js 프로젝트가 정적 export로 배포되는 경우, 서버 액션, API Route, 동적 서버 렌더링이 필요한 코드와 충돌할 수 있습니다.
LastFix 랜딩처럼 정적 페이지로 운영하는 프로젝트는 output: export 설정을 유지해야 합니다. 이때 AI가 문의 폼이나 데이터 저장 기능을 추가하면서 API Route를 만들면 빌드나 배포 구조가 깨질 수 있습니다.
확인할 것:
- next.config.ts에 output: export가 있는가
- app/api 폴더나 서버 액션을 새로 만들지 않았는가
- 배포 시 필요한 데이터가 빌드 타임에 접근 가능한가
- 정적 페이지에서 외부 제출 엔드포인트를 쓰는 방식이 맞는가
정적 배포 프로젝트라면 "동작하는 코드"보다 "정적 export 가능한 코드"가 더 중요합니다.
LastFix에서는 이렇게 확인합니다
Vercel·Next.js 배포 오류 요청이 들어오면 보통 다음 순서로 봅니다.
- 배포 로그에서 첫 번째 원인 후보 확인
- 로컬 빌드 재현 여부 확인
- 환경 변수와 배포 설정 확인
- import 경로와 파일명 대소문자 확인
- 서버/클라이언트 컴포넌트 경계 확인
- 정적 export, API Route, 서버 액션 충돌 여부 확인
- 필요한 최소 수정 후 다시 빌드
처음부터 전체 코드를 갈아엎지 않습니다. 배포 오류는 작은 설정 하나로 해결되는 경우도 많고, 반대로 작은 코드 한 줄이 빌드 전체를 막고 있을 수도 있습니다. 중요한 것은 범위를 먼저 좁히는 것입니다.
정리
로컬에서는 되는데 Vercel 배포가 안 된다면 다음 순서로 확인하세요.
- 배포 로그의 첫 번째 의미 있는 에러
- 환경 변수 등록 여부
- import 경로와 파일명 대소문자
- window, document, localStorage 사용 위치
- 정적 export와 동적 기능 충돌
AI에게 세 번 이상 맡겨도 같은 배포 오류가 반복된다면, 더 고치기 전에 원인 진단부터 받는 편이 빠릅니다. 관련해서는 비개발자의 바이브코딩, 왜 배포에서 자주 막힐까?도 함께 참고해보세요.