Dev

Feb 13, 2026

마지막 업데이트 Apr 9, 2026

Vercel 배포 오류 가이드: 로컬에서는 되는데 운영에서 깨질 때 체크리스트

“로컬에서는 잘 되는데 Vercel에 올리면 깨진다”는 말은 막연해 보이지만, 실제로는 몇 가지 반복되는 실패 유형 안에 들어가는 경우가 많습니다.

가장 빨리 복구하는 방법은 모든 배포 실패를 같은 문제처럼 다루지 않는 것입니다. Vercel에서는 먼저 이 정도로 나누는 것이 가장 실용적입니다.

build 실패
runtime 또는 function 실패
domain 또는 DNS 실패
우선 rollback부터 해야 하는 나쁜 운영 배포

이 글은 그 운영 흐름 기준의 가이드입니다. 원인 후보를 길게 늘어놓기보다, 어떤 실패를 어떤 표면에서 확인하고 어떻게 복구 순서를 잡아야 하는지에 집중합니다.

Vercel 배포 복구 흐름

Quick answer

Vercel 배포가 깨졌다면 이 순서로 시작하는 것이 가장 효율적입니다.

문제가 build인지, runtime인지, domain인지 먼저 구분한다
코드를 고치기 전에 관련 로그를 먼저 본다
환경 변수와 재배포 필요 여부를 확인한다
Preview와 Production 가정을 비교한다
Production이 이미 망가졌다면 rollback을 먼저 고려한다

이 순서가 세 군데를 동시에 바꾸고 다시 배포하는 것보다 훨씬 빠릅니다.

1단계: 코드를 건드리기 전에 실패 유형부터 나누기

이 1분이 제일 중요합니다.

먼저 한 가지를 물어야 합니다.

build 단계에서 배포가 실패했는가
아니면 배포는 됐는데 앱을 열었을 때 깨지는가

그리고 하나를 더 나눕니다.

Vercel 배포 URL은 열리는데 custom domain만 안 되는가

이렇게 하면 실전적으로 세 가지로 나뉩니다.

실패 유형	대표 신호	먼저 볼 표면
build 실패	deployment가 usable 상태가 안 됨	build logs
runtime 실패	deployment는 ready인데 페이지나 함수가 깨짐	runtime logs
domain 실패	deployment URL은 되는데 custom domain이 안 됨	DNS / SSL / domain 설정

이 구분을 건너뛰면 엉뚱한 층을 계속 디버깅하게 됩니다.

build 실패라면 가정부터 좁히기

Vercel build troubleshooting 문서도 먼저 build log를 보라고 안내합니다. 이게 맞습니다.

배포가 아예 healthy 상태가 되지 않는다면, 원인은 대개 신비한 것이 아니라 반복되는 패턴입니다.

환경 변수 누락 또는 오타
의존성 해석 문제
runtime에 필요한 패키지가 devDependencies에 들어감
Node 또는 패키지 매니저 버전 차이
대소문자 경로 불일치
build 중 외부 API 호출 실패

환경 변수는 여전히 가장 큰 원인입니다

Vercel 환경 변수 문서는 환경 변수 변경이 이전 배포에는 적용되지 않고, 새 배포에만 적용된다고 설명합니다.

이 말은 두 가지를 뜻합니다.

현재 배포는 환경 변수 하나 때문에 바로 깨질 수 있다
대시보드에서 값을 고쳐도 새 배포를 만들기 전까지는 앱이 그 값을 보지 못한다

확인할 것:

변수가 올바른 환경에 존재하는가
코드가 정확한 변수명을 읽는가
값 수정 후 새 배포를 만들었는가

로컬 정합성 확인에는:

vercel env pull

이 유용합니다.

그리고 Vercel 문서에 따르면 vercel build나 vercel dev를 쓴다면 vercel pull이 더 잘 맞습니다. .vercel/ 아래에 환경 변수와 프로젝트 설정을 로컬 캐시로 저장하기 때문입니다.

Preview와 Production은 다를 수 있습니다

Vercel 환경 변수 문서는 Preview 변수는 non-production branch에 적용되고, branch-specific Preview 변수는 공통 Preview 값을 덮어쓸 수 있다고 설명합니다.

즉 Preview가 멀쩡해 보여도 Production이 깨질 수 있습니다.

Production 변수 자체가 없거나
값이 다르거나
특정 Preview branch override가 실제 문제를 가렸을 수 있습니다

버전과 경로 가정도 같이 보기

build 실패는 이런 문제에서도 자주 납니다.

runtime에 필요한 패키지가 devDependencies에 숨어 있음
lockfile drift
Node 버전 차이
Linux에서만 깨지는 import path 대소문자 mismatch

전형적인 “로컬에서는 되는데 CI에서는 깨지는” 문제들입니다.

runtime 실패라면 build log보다 runtime log로 넘어가기

배포는 ready 상태인데 앱이 깨진다면, build log만 계속 보는 것은 시간 낭비일 때가 많습니다.

Vercel은 runtime logs를 별도로 제공합니다. 아래 같은 문제는 이쪽이 더 정확합니다.

server function 실패
request 시점 환경 변수 가정 오류
runtime API secret 누락
외부 서비스 장애
첫 요청 이후에만 드러나는 코드 경로 문제

대표 패턴:

페이지는 열리는데 API가 실패한다
어떤 route는 되고 어떤 route는 500이 난다
Preview는 되는데 Production 요청만 실패한다
deployment URL은 열리는데 실제 기능이 깨진다

이 단계에서는 아래 순서가 좋습니다.

runtime log 확인
실패한 request path 확인
Production과 Preview env 값 비교
filesystem이나 process 상태 가정이 코드에 없는지 확인

배포가 이미 요청을 받고 있다면, 원래 build output보다 runtime 증거가 더 중요합니다.

domain 실패는 앱 실패와 분리해서 보기

가장 비싼 실수 중 하나가 domain 문제를 앱 문제처럼 보는 것입니다.

Vercel deployment URL은 열리는데 custom domain만 안 된다면, 앱 코드는 멀쩡할 가능성이 큽니다.

대표적인 domain-only 실패:

deployment URL은 되는데 custom domain은 안 됨
apex는 되는데 www는 안 됨
HTTPS가 불안정하거나 인증서가 덜 붙음
redirect가 loop를 만듦

이 시점에서는 더 이상 앱 코드가 1순위 문제가 아닐 수 있습니다.

확인할 것:

apex와 www를 둘 다 Vercel에 추가했는가
공개 호스트를 하나로 정했는가
DNS 레코드
SSL 상태
redirect 동작

이 유형이라면 다음 문서는 보통 코드 수정이 아니라 Cloudflare DNS 가이드입니다.

복구를 우선할 때: rollback도 정상적인 선택지다

Production이 이미 사용자에게 깨진 상태라면, 최선의 첫 행동이 반드시 원인 분석은 아닙니다.

Vercel은 Production rollback 흐름을 문서화하고 있습니다. 이게 중요한 이유는, 일단 서비스를 복구한 다음 문제 배포를 별도로 분석할 수 있기 때문입니다.

rollback이 먼저인 경우:

새 배포가 명확한 regression을 만들었다
이미 사용자가 영향받고 있다
원인 분석보다 서비스 복구가 우선이다

이럴 때는 깨진 상태 위에서 핫픽스를 덧붙이는 것보다 rollback이 더 안전할 수 있습니다.

실전 디버깅 순서

시간이 없을 때는 이 순서가 가장 덜 아픕니다.

build, runtime, domain 중 무엇인지 구분
관련 로그를 한 번 차분히 읽기
환경 변수와 재배포 필요 여부 확인
Preview와 Production 가정 비교
의존성, Node 버전, path casing 확인
deployment URL과 custom domain 건강 상태를 분리해서 보기
Production 영향이 크면 rollback 먼저 고려

이 순서가 랜덤 수정과 재배포 반복을 줄여줍니다.

흔한 실수

1. runtime 문제를 build log에서 계속 찾는 경우

배포가 이미 요청을 받고 있다면 runtime log가 더 정확한 증거인 경우가 많습니다.

2. env 값을 바꿨는데 재배포를 안 하는 경우

Vercel 문서도 환경 변수 변경은 이전 배포에 적용되지 않는다고 분명히 적고 있습니다.

3. Preview를 너무 믿는 경우

Preview는 강력하지만, Production env가 다르면 Production 성공까지 보장하지 않습니다.

4. domain만 깨졌는데 앱을 계속 고치는 경우

deployment URL이 열리면, 앱 자체가 주원인이 아닐 수 있습니다.

5. 라이브 장애를 복구보다 분석부터 하려는 경우

때로는 rollback이 더 빠르고 안전한 첫 행동입니다.

FAQ

Q. 제일 먼저 뭘 봐야 하나요?

실패 유형부터 나누세요. build, runtime, domain은 증거도 다르고 해결 방법도 다릅니다.

Q. 환경 변수 고쳤는데 왜 바로 안 고쳐졌나요?

Vercel 문서 기준으로 env 변경은 이전 배포에 적용되지 않습니다. 값을 바꾼 뒤 새 배포가 필요합니다.

Q. Preview는 되는데 Production만 왜 깨지나요?

Production 환경 변수나 값이 다르거나, Preview branch override가 문제를 가렸을 가능성이 큽니다.

Q. 언제 rollback을 먼저 해야 하나요?

Production이 이미 사용자에게 깨졌고, 서비스를 먼저 복구하는 것이 가장 안전할 때입니다.

Official References

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.