비개발자의 바이브코딩, 왜 배포에서 자주 막힐까?
로컬에서는 잘 되는데 Vercel, Netlify에 배포할 때 에러가 나는 이유. 바이브코딩으로 만든 앱이 배포 단계에서 실패하는 구조적 원인과 해결 방향을 설명합니다.
"내 컴퓨터에서는 잘 되는데, 배포만 하면 안 돼요."
바이브코딩을 하는 비개발자에게 가장 흔한 좌절의 순간입니다. Cursor나 Bolt로 열심히 만들고, 로컬에서 테스트까지 마치고, 의기양양하게 Vercel에 배포 버튼을 누르는데 — 빨간 에러 화면이 나옵니다.
AI에게 "배포 에러 고쳐줘"라고 하면 로컬 코드를 이것저것 고치기 시작하는데, 로컬에서는 이미 잘 되고 있거든요. 문제는 코드가 아니라 환경입니다. 이 글에서는 왜 이런 일이 일어나는지, 그리고 어떻게 접근해야 하는지를 비개발자 눈높이에서 설명합니다.
로컬과 배포 환경은 완전히 다릅니다
내 컴퓨터(로컬)에서 앱을 실행할 때와 Vercel이나 Netlify 같은 서비스에 배포할 때는 실행 환경이 완전히 다릅니다.
로컬 환경에는 내가 설치한 Node.js 버전, 운영체제 설정, 환경 변수(.env 파일) 등이 있습니다. 이것들은 AI가 코드를 짤 때 자동으로 참조하는 것들이죠.
하지만 Vercel에 배포하면, Vercel의 서버에서 처음부터 다시 빌드합니다. 내 컴퓨터에 있던 .env 파일도 없고, Node.js 버전도 다를 수 있고, 파일 시스템의 동작 방식도 다릅니다.
AI는 이 차이를 인식하지 못합니다. AI는 내 컴퓨터에서 잘 동작하는 코드를 만들어줄 뿐, 배포 환경의 제약 조건까지 고려하지 않습니다.
가장 흔한 배포 실패 원인 3가지
1. 환경 변수 누락
로컬에 .env 파일로 저장해둔 API 키나 데이터베이스 주소가 Vercel 환경에는 설정되어 있지 않은 경우입니다. 이건 가장 흔하면서도 가장 찾기 어려운 원인입니다. 에러 메시지가 "Cannot read property of undefined" 같은 모호한 형태로 나오기 때문입니다.
Vercel 대시보드의 Environment Variables 설정에서 로컬 .env 파일의 값을 하나하나 옮겨야 합니다.
2. 빌드 타임 vs 런타임 차이
Next.js 같은 프레임워크는 빌드할 때 페이지를 미리 생성합니다. 로컬에서 개발 모드(npm run dev)로 돌릴 때는 모든 페이지가 실시간으로 렌더링되지만, 빌드(npm run build)할 때는 사전에 데이터를 가져와서 HTML을 만들어둡니다.
이 과정에서 API가 응답하지 않거나, 데이터 형식이 예상과 다르면 빌드 자체가 실패합니다. 로컬 개발 모드에서는 발생하지 않던 문제가 빌드에서만 터지는 이유입니다.
3. 대소문자 민감도
macOS는 파일 이름의 대소문자를 구분하지 않지만, Linux(대부분의 배포 서버)는 구분합니다. 'Components/Header.tsx'로 import했는데 실제 파일이 'components/header.tsx'라면, 내 맥에서는 문제없이 돌아가지만 배포 서버에서는 "Module not found" 에러가 발생합니다.
AI에게 배포 에러를 물어보는 올바른 방법
배포 에러가 나면 AI에게 이렇게 물어보세요:
1. Vercel(또는 Netlify)의 빌드 로그 전체를 복사해서 붙여넣기
2. "로컬에서는 정상 동작하는데, 배포 빌드에서 이 에러가 발생해"라고 맥락 설명
3. "코드를 수정하지 말고, 원인만 먼저 분석해줘"라고 요청
세 번째가 중요합니다. AI에게 바로 "고쳐줘"라고 하면, 로컬 코드를 건드리기 시작합니다. 로컬에서는 이미 잘 돌아가는 코드를요. 원인을 먼저 파악한 뒤에 수정 방향을 잡아야 합니다.
그래도 해결이 안 되는 경우가 많습니다. 배포 환경 문제는 AI가 가장 취약한 영역 중 하나이기 때문입니다. AI는 Vercel의 빌드 프로세스를 직접 확인할 수 없고, 내 프로젝트의 설정 파일들 사이의 충돌을 종합적으로 판단하기 어렵습니다.
배포 문제야말로 사람의 판단이 필요한 순간
배포 에러의 본질은 '환경과 설정의 문제'입니다. 코드 로직이 아니라 인프라와 설정의 조합에서 발생하는 문제이기 때문에, 코드만 보는 AI에게는 구조적으로 어려운 영역입니다.
경험 있는 개발자는 에러 메시지를 보면 "이건 환경 변수 문제", "이건 빌드 설정 문제"를 빠르게 판단할 수 있습니다. 비개발자가 몇 시간 동안 AI와 씨름할 문제를, 짧은 점검으로 좁혀낼 수 있는 거죠.
LastFix는 이런 상황에서 단건 해결로 시작할 수 있습니다. 배포 로그와 설정 파일을 확인하고, 필요한 수정이나 설정 반영까지 범위를 정해 진행합니다.
로컬에서는 되는데 배포에서 막힌다면, 혼자 오래 붙잡기보다 문제 상황을 남기고 상담해보는 편이 더 빠를 수 있습니다.
배포 전 체크리스트
바이브코딩으로 만든 앱을 배포하기 전, 이 목록을 확인하세요:
- .env 파일의 모든 환경 변수를 배포 서비스에도 등록했는가?
- npm run build를 로컬에서 먼저 실행해봤는가? (개발 모드에서는 안 보이는 에러를 잡을 수 있습니다)
- import 경로의 대소문자가 실제 파일명과 정확히 일치하는가?
- API 엔드포인트가 배포 환경에서도 접근 가능한가? (localhost:3000 같은 로컬 주소를 사용하고 있지는 않은가?)
이 체크리스트만으로도 많은 배포 실패를 예방할 수 있습니다.