바이브 코딩 앱 배포할 때 자주 나는 에러들

2026년 6월 28일 · 배포 · 9분 읽기

로컬에서는 완벽하게 잘 되던 앱이 배포하면 갑자기 안 되는 경우가 있습니다. "분명히 로컬에서는 됐는데"라는 상황입니다. 바이브 코딩으로 만든 앱을 Vercel이나 Cloudflare Pages에 배포할 때 자주 발생하는 에러들과 해결 방법을 정리했습니다.

배포 전에 꼭 확인할 것

배포 에러의 상당수는 환경 차이에서 옵니다. 로컬(내 컴퓨터)과 배포 서버는 다른 환경입니다. 이 차이를 이해하는 것이 배포 에러를 빠르게 해결하는 첫걸음입니다.

에러 1: 환경 변수가 없어서 앱이 작동하지 않는 경우

가장 흔한 배포 에러입니다. 로컬에서는 .env.local 파일에 환경 변수를 넣어두고 사용합니다. 그런데 이 파일은 .gitignore에 포함되어 있어서 배포 서버에는 올라가지 않습니다.

증상

배포 후 API 호출이 안 됨
데이터베이스 연결 실패
인증이 안 됨
콘솔에 undefined 관련 에러

해결 방법

배포 플랫폼의 환경 변수 설정에서 직접 추가해야 합니다.

Vercel: 프로젝트 → Settings → Environment Variables
Cloudflare Pages: 프로젝트 → Settings → Environment Variables

로컬의 .env.local 파일을 열어서 사용하는 변수들을 하나씩 추가하세요. Next.js라면 NEXT_PUBLIC_으로 시작하는 변수와 그렇지 않은 변수를 구분해서 추가해야 합니다.

환경 변수를 추가한 후에는 반드시 재배포가 필요합니다. 변수를 추가해도 기존 배포에는 바로 적용되지 않습니다.

에러 2: 빌드 실패 (Build Failed)

로컬에서는 npm run dev로 개발 서버만 돌렸는데, 배포할 때는 npm run build를 통해 프로덕션 빌드를 생성합니다. 개발 모드에서는 통과되던 오류가 빌드 시에는 에러로 처리되는 경우가 있습니다.

자주 나는 빌드 에러

TypeScript 타입 에러

개발 중에는 타입 에러를 무시하고 계속 개발할 수 있지만, 빌드 시에는 타입 에러가 있으면 빌드가 실패합니다.

Type error: Type 'string | undefined' is not assignable to type 'string'

해결: 배포 전에 로컬에서 npm run build를 직접 실행해보세요. 배포 서버에서 나는 빌드 에러를 미리 확인할 수 있습니다.

Import 경로 오류

윈도우에서 개발하다가 리눅스 서버에 배포하면 파일 경로의 대소문자 구분 때문에 에러가 날 수 있습니다. 윈도우는 import Button from './button'이 Button.tsx를 찾아주지만, 리눅스는 정확히 button.tsx 또는 Button.tsx로 써야 합니다.

패키지 설치 실패

로컬에서 수동으로 설치한 패키지가 package.json에 기록되지 않은 경우입니다.

Module not found: Can't resolve 'some-package'

해결: package.json의 dependencies에 해당 패키지가 있는지 확인하세요. 없으면 npm install some-package --save로 다시 설치합니다.

에러 3: 배포 후 API 라우트가 작동하지 않는 경우

Next.js의 API Routes는 서버리스 함수로 배포됩니다. 로컬에서는 24시간 항상 켜져 있는 서버처럼 동작하지만, 배포 환경에서는 요청이 있을 때만 실행됩니다.

타임아웃 문제

Vercel 무료 플랜의 서버리스 함수는 최대 10초까지만 실행됩니다. 외부 API를 여러 개 호출하거나 데이터베이스 쿼리가 복잡한 경우 타임아웃이 발생할 수 있습니다.

504 Gateway Timeout

해결: API 호출을 최적화하거나, Pro 플랜으로 업그레이드해서 타임아웃 제한을 늘리세요.

파일 시스템 접근 불가

로컬에서는 서버에서 파일을 읽고 쓸 수 있지만, Vercel 같은 서버리스 환경에서는 파일 시스템이 읽기 전용입니다. 파일을 저장하려면 S3, Cloudflare R2 같은 외부 스토리지를 사용해야 합니다.

에러 4: CORS 에러 (배포 후에 발생하는 경우)

로컬에서는 localhost:3000에서 개발하다가 배포하면 도메인이 바뀝니다. CORS 설정에 로컬호스트 주소만 허용해뒀다면, 배포된 도메인에서는 CORS 에러가 납니다.

Access to fetch at 'https://api.example.com' from origin 'https://myapp.vercel.app'
has been blocked by CORS policy

해결: API 서버의 CORS 허용 목록에 배포된 도메인을 추가하세요. 개발 중에는 localhost:3000과 프로덕션 도메인을 모두 허용해두는 것이 편리합니다.

배포 에러를 빠르게 해결하는 방법

배포 로그 확인하기

Vercel과 Cloudflare Pages 모두 배포 로그를 제공합니다. 어느 단계에서 에러가 났는지, 어떤 에러 메시지가 나왔는지 확인할 수 있습니다. 대시보드에서 실패한 배포를 클릭하면 상세 로그를 볼 수 있습니다.

로컬에서 프로덕션 빌드 테스트하기

배포 전에 로컬에서 프로덕션 빌드를 테스트하는 습관을 들이면 배포 에러를 많이 줄일 수 있습니다.

# 빌드 테스트
npm run build

# 빌드된 결과 실행
npm run start

이렇게 하면 배포 서버와 거의 동일한 환경에서 테스트할 수 있습니다.

에러 메시지를 그대로 검색하기

배포 에러 메시지는 대부분 특정 패턴이 있습니다. 에러 메시지를 그대로 복사해서 구글에 검색하면 이미 같은 문제를 겪고 해결한 사람의 글을 찾을 수 있습니다. GitHub Issues나 Stack Overflow, Vercel 공식 문서에 자주 나오는 에러들의 해결 방법이 정리되어 있습니다.

정리

배포 에러의 대부분은 환경 변수 누락, 빌드 시 타입 에러, 서버리스 환경의 제약 때문에 발생합니다. 배포 전에 npm run build를 로컬에서 먼저 실행해보고, 환경 변수를 배포 플랫폼에 제대로 설정했는지 확인하는 것만으로도 많은 에러를 예방할 수 있습니다.

배포하다 막혔다면

어떤 에러가 나는지, 어떤 플랫폼에 배포하고 있는지 알려주시면 같이 해결해드립니다. 24시간 내로 회신드립니다.

도움 요청하기 →