Vercel 배포가 실패할 때 가장 많은 원인 5가지
Vercel 배포 오류, 배포 실패, 하얀 화면, 404의 가장 흔한 원인 다섯 가지와 오류 문구별로 고치는 곳을 정리했어요.
Vercel 배포가 실패하는 원인은 대부분 다섯 가지 중 하나예요. 환경 변수 누락, 파일 이름 대소문자, 화면 이동(라우팅) 설정, 타입 오류, Node 버전이나 패키지 잠금 파일 문제예요. 배포 로그 맨 아래의 오류 문장을 보면 어느 쪽인지 바로 알 수 있어요.
먼저 오류 문장을 찾아요
Vercel 프로젝트에서 Deployments → 실패한 배포 → Building 로그를 열어요. Error: Command "npm run build" exited with 1은 결과일 뿐이고, 진짜 원인은 그 바로 위 몇 줄에 있어요. 배포는 됐는데 화면이 안 나온다면 사이트에서 F12를 눌러 Console 탭을 봐요.
| 이런 문장이 보이면 | 원인 | 바로 아래 번호 |
|---|---|---|
supabaseUrl is required., undefined 관련 오류 | 환경 변수 누락 | 1 |
Module not found: Can't resolve, Could not resolve | 파일 이름 대소문자 | 2 |
첫 화면은 되는데 새로고침하면 404: NOT_FOUND | 화면 이동 설정 | 3 |
Type error:, Failed to compile | 타입 오류 | 4 |
npm ci can only install packages when your package.json and package-lock.json ... are in sync, Node 버전 경고 | 잠금 파일, Node 버전 | 5 |
1. 환경 변수가 빠졌어요
가장 흔해요. 내 컴퓨터의 .env 파일은 보안 때문에 깃허브에 올라가지 않아서, Vercel은 그 값을 몰라요.
- Settings → Environment Variables에
.env의 이름과 값을 똑같이 넣어요. - 브라우저에서 쓰는 값은 이름 앞에 붙는 말이 정해져 있어요. Next.js는
NEXT_PUBLIC_, Vite는VITE_로 시작해야 화면 코드에서 읽혀요. - 넣은 뒤에는 꼭 다시 배포(Redeploy) 해요. 저장만 하면 이미 만들어진 배포에는 적용되지 않아요.
2. 파일 이름 대소문자가 달라요
맥이나 윈도우는 Cart.tsx와 cart.tsx를 같은 파일로 봐 주지만, Vercel 서버는 다른 파일로 봐요. 그래서 내 컴퓨터에선 되는데 배포에서만 Module not found: Can't resolve './components/Cart' 같은 오류가 나요.
- 오류에 나온 경로와 실제 파일 이름을 한 글자씩 비교해요.
- 깃은 대소문자만 바꾼 이름 변경을 놓칠 때가 있어서,
git mv cart.tsx Cart.tsx처럼 바꿔 주는 게 안전해요.
3. 새로고침하면 404가 나요
리액트 라우터 같은 화면 이동을 쓰는 Vite 프로젝트는 첫 화면만 진짜 파일이 있고, /about 같은 주소는 브라우저 안에서 만들어져요. 그래서 그 주소로 바로 들어오거나 새로고침하면 Vercel이 파일을 못 찾아요.
프로젝트 맨 위 폴더에 vercel.json을 만들고 아래처럼 넣어 주면 모든 주소를 첫 화면으로 보내 줘요.
{
"rewrites": [{ "source": "/(.*)", "destination": "/" }]
}
Next.js는 이 설정이 필요 없어요. Next.js에서 404가 난다면 파일 위치(app 폴더 구조)를 먼저 확인해요.
4. 타입 오류로 빌드가 멈춰요
개발 서버(npm run dev)는 타입 오류가 있어도 화면을 띄워 주지만, 배포 빌드는 오류가 있으면 멈춰요. 그래서 "어제까지 잘 되던 게 배포만 안 돼요"가 생겨요.
- 내 컴퓨터에서
npm run build를 직접 돌려 보면 같은 오류를 미리 볼 수 있어요. - 오류를 끄는 설정(
ignoreBuildErrors)으로 넘어가면 당장은 올라가도, 실제 기능이 깨진 채로 나갈 수 있어서 권하지 않아요.
5. Node 버전이나 잠금 파일이 달라요
package.json과package-lock.json이 서로 안 맞으면 설치 단계에서 멈춰요. 내 컴퓨터에서npm install을 한 번 하고 바뀐 잠금 파일까지 같이 올려요.package-lock.json,pnpm-lock.yaml,yarn.lock이 한 폴더에 여러 개 있으면 어떤 걸로 설치할지 헷갈려 해요. 쓰는 것 하나만 남겨요.- 내 컴퓨터와 Vercel의 Node 버전이 다르면 Settings에서 Node.js Version을 맞추거나,
package.json의engines에 적어 둬요.
혼자 하기 어려운 신호
- 위 다섯 가지를 다 확인했는데 로그에 처음 보는 오류가 계속 바뀌어 나와요.
- 하나를 고치면 다른 오류가 생기는 일이 반복돼요.
- 배포는 됐지만 로그인, 결제, 회원 정보가 이상하게 동작해요. 이건 배포 문제가 아니라 코드 구조 문제일 때가 많아요.
막히면 이어서 마무리해 드려요
배포 오류는 원인만 찾으면 금방 끝나는 경우가 많아요. 혼자 붙잡고 있기 답답하다면 날다데브가 코드를 보고 고칠 곳을 쉬운 말로 정리해 드려요. 도와드리는 범위는 바이브코딩 마무리·배포에서 볼 수 있고, 배포 로그 캡처와 함께 무료 상담 문의를 남겨 주세요. 처음부터 순서대로 보고 싶다면 바이브코딩으로 만든 사이트, 인터넷에 올리는 방법을 먼저 읽어 보세요.