2026년 5월 2일

Bolt.new 배포 오류 해결: Vercel에서 실패하는 대표 원인

Bolt.new에서 만든 앱을 Vercel로 옮기거나 배포할 때 로컬 미리보기와 다르게 실패하는 이유를 환경 변수, 빌드 설정, 패키지, 경로 문제 중심으로 정리했습니다.

Bolt.new는 아이디어를 빠르게 화면으로 만들기에 좋은 도구입니다. 브라우저에서 바로 프로젝트가 뜨고, 미리보기까지 한 화면에서 되니까 처음 만들 때는 속도가 꽤 시원합니다.

그런데 미리보기에서 잘 돌아가던 앱을 Vercel에 배포하려고 하면 갑자기 막히는 일이 있습니다. "Bolt에서는 됐는데 왜 Vercel에서는 안 되지?"라는 상황입니다.

이 문제는 이상한 일이 아닙니다. Bolt의 실행 환경과 Vercel의 배포 빌드 환경은 다릅니다. 미리보기에서 동작한 코드를 실제 배포 가능한 프로젝트로 정리하는 단계가 한 번 더 필요할 수 있습니다.

Bolt 미리보기와 Vercel 배포는 같은 테스트가 아니다

Bolt 안에서 실행되는 미리보기는 개발 중인 상태를 빠르게 보여주는 데 가깝습니다. 반면 Vercel 배포는 프로젝트를 처음부터 설치하고, 빌드하고, 정적 파일이나 서버 실행 결과로 내보내는 과정입니다.

개발 환경에서는 넘어가던 문제가 빌드 단계에서는 바로 드러납니다. import 경로가 틀렸거나, 환경 변수가 없거나, 브라우저에서만 쓸 수 있는 코드를 서버 빌드 중에 실행하면 배포가 실패합니다.

그래서 Bolt에서 잘 됐다는 사실은 중요한 단서지만, 배포 가능하다는 보장은 아닙니다. 배포 로그를 기준으로 다시 봐야 합니다.

Vercel은 보통 package.json을 보고 install, build 명령을 실행합니다. Bolt가 만든 프로젝트 안에 어떤 프레임워크가 들어 있는지, build 명령이 무엇인지가 중요합니다.

확인할 것:

가끔 AI가 프로젝트를 수정하면서 필요 없는 패키지를 섞거나, 프레임워크를 바꾸는 과정에서 build 명령이 애매해집니다. 이때 Vercel은 어디서 무엇을 빌드해야 할지 모른 채 실패합니다.

Supabase, Firebase, Clerk, Stripe, 토스페이먼츠 같은 서비스를 붙였다면 환경 변수를 확인해야 합니다.

Bolt 안에서 설정한 값이나 로컬 .env에 있는 값은 Vercel 프로젝트에 자동으로 들어가지 않습니다. Vercel의 Project Settings에서 Environment Variables에 직접 등록해야 합니다.

배포 로그나 브라우저 콘솔에 이런 형태가 보이면 환경 변수부터 의심합니다.

환경 변수를 추가한 뒤에는 반드시 재배포해야 합니다. 값만 넣고 기존 배포를 다시 열어보면 바뀌지 않은 상태일 수 있습니다.

Bolt로 UI를 빠르게 만들다 보면 window, document, localStorage 같은 브라우저 전용 객체를 컴포넌트 상단에서 바로 쓰는 코드가 생길 수 있습니다.

개발 미리보기에서는 별 문제 없어 보이지만, Next.js 빌드에서는 서버 쪽에서 컴포넌트를 해석하는 순간 에러가 납니다. 대표적인 메시지는 window is not defined, document is not defined 같은 형태입니다.

확인할 것:

이 문제는 AI가 겉보기 동작을 맞추려고 코드를 빠르게 만들 때 자주 생깁니다.

macOS나 브라우저 기반 개발 환경에서는 파일 경로 대소문자 문제가 늦게 드러날 수 있습니다. 하지만 Vercel의 빌드 환경에서는 대소문자를 더 엄격하게 봅니다.

예를 들어 실제 파일은 components/Button.tsx인데 import에서 components/button이라고 쓰면 배포에서 Module not found가 날 수 있습니다.

Bolt가 파일을 만들고 이름을 바꾸는 과정에서 이런 일이 생깁니다. 특히 컴포넌트가 많아지고, AI가 폴더를 정리해준 뒤에 배포가 깨졌다면 경로를 꼭 확인해야 합니다.

배포 로그에서 Module not found가 보이면 마지막 줄보다 어떤 import 경로를 찾지 못했는지를 먼저 보세요.

프로젝트에 따라 Vercel에서 정적으로 내보내야 하는 경우가 있고, 서버 기능이 필요한 경우가 있습니다. AI가 API Route, 서버 액션, 파일 업로드, 세션 처리 같은 기능을 만들었다면 배포 방식과 충돌할 수 있습니다.

특히 원래 단순 랜딩페이지였는데 AI가 문의 폼을 만들면서 app/api 폴더를 추가하거나, 서버에서만 처리해야 하는 코드를 넣는 경우가 있습니다. 이러면 정적 export가 필요한 프로젝트에서는 배포 구조가 깨집니다.

"미리보기에서는 제출 버튼이 눌렸다"와 "정적 사이트로 안전하게 배포된다"는 다른 이야기입니다. 문의, 결제, 로그인 같은 기능은 배포 방식까지 같이 봐야 합니다.

Bolt 배포 오류를 AI에게 다시 물어볼 때는 로그를 통째로 주고 바로 수정시키기보다, 원인 분류부터 시키는 편이 좋습니다.

이렇게 물어보세요.

AI가 전체 프로젝트를 다시 정리하겠다고 하면 잠깐 멈추는 게 좋습니다. 배포 오류는 작은 원인 하나로 생기는 경우가 많습니다.

Bolt.new에서 만든 앱이 Vercel 배포에서 실패한다면 다음 순서로 확인하세요.

Bolt는 시작을 빠르게 해주는 도구입니다. 다만 실제 운영 배포는 한 번 더 정리해야 할 수 있습니다. 같은 배포 오류를 여러 번 고쳐도 실패한다면, 코드를 더 만들기보다 배포 환경과 프로젝트 구조를 먼저 확인하는 편이 빠릅니다.

AI·바이브코딩으로 해결되지 않는 개발 이슈, 먼저 원인부터 확인하세요

Cursor 에러, Vercel·Next.js 배포 실패, 결제·예약 연동 오류, 소규모 기능 개발을 단건 중심으로 진단합니다. 월 구독 파트너는 정식 상품을 준비 중입니다.