Vercel 배포 후 흰 화면이 뜰 때 확인할 7가지

1. 빌드는 성공했는지 먼저 본다

흰 화면이라고 해서 모두 같은 문제가 아닙니다.

먼저 Vercel의 Deployments 화면에서 배포 상태를 확인하세요.

• 빌드가 실패했다면: 사이트가 제대로 배포되지 않은 상태
• 빌드는 성공했지만 화면이 비었다면: 브라우저 실행 중 에러일 가능성
• 특정 URL만 비었다면: 라우팅이나 데이터 로딩 문제일 가능성

빌드가 실패했다면 브라우저 화면보다 배포 로그를 먼저 봐야 합니다. 반대로 배포는 초록색인데 화면만 비어 있다면 브라우저 개발자 도구의 Console과 Network 탭이 더 중요합니다.

2. 브라우저 콘솔의 첫 번째 에러를 확인한다

Vercel 배포 후 흰 화면은 브라우저에서 자바스크립트가 실행되다가 멈출 때 자주 나옵니다. 이때 콘솔에는 대개 첫 번째 원인이 찍혀 있습니다.

자주 보이는 문구는 이렇습니다.

• Cannot read properties of undefined
• process is not defined
• Failed to fetch
• Hydration failed
• ChunkLoadError
• Module not found

AI에게 물어볼 때도 "흰 화면이야"라고만 하지 말고 콘솔의 첫 번째 빨간 에러를 같이 전달해야 합니다. 같은 흰 화면이라도 환경 변수 문제, API 주소 문제, hydration 문제는 해결 방향이 완전히 다릅니다.

3. 환경 변수가 Vercel에 들어 있는지 본다

가장 흔한 원인입니다.

로컬에서는 .env.local에 Supabase URL, Firebase 설정, API 주소가 들어 있습니다. 하지만 Vercel은 그 파일을 자동으로 읽지 않습니다. Vercel Project Settings의 Environment Variables에 따로 넣어야 합니다.

확인할 것:

• 로컬 .env에 있는 키 이름이 Vercel에도 있는가
• Production 환경에 체크되어 있는가
• 클라이언트에서 쓰는 값에는 NEXT_PUBLIC_ 접두어가 필요한가
• 값을 추가한 뒤 다시 배포했는가

환경 변수가 비어 있으면 화면 컴포넌트가 데이터를 읽다가 멈추고, 결과적으로 흰 화면처럼 보일 수 있습니다.

4. localhost나 예전 미리보기 주소가 남아 있는지 찾는다

AI가 만든 프로젝트에는 개발 중 임시 주소가 남아 있는 경우가 많습니다.

검색해볼 값은 단순합니다.

• localhost
• 127.0.0.1
• .vercel.app 미리보기 주소
• 예전 Netlify 주소
• 테스트 API 주소

운영 배포에서 브라우저가 localhost로 요청을 보내면 사용자의 컴퓨터 안에서 API를 찾게 됩니다. 당연히 실패합니다. 화면이 API 응답을 기다리다가 빈 상태로 멈춘다면 이 가능성을 봐야 합니다.

5. import 경로와 이미지 경로의 대소문자를 확인한다

맥에서는 괜찮았는데 Vercel에서만 깨진다면 파일명 대소문자를 의심해야 합니다. Vercel의 빌드 환경은 보통 Linux라서 파일명 대소문자를 정확히 구분합니다.

예를 들어 실제 파일은 Header.tsx인데 import에서 header.tsx로 부르면 로컬에서는 넘어가도 배포에서 실패할 수 있습니다.

이미지도 마찬가지입니다. public/images/Hero.png를 코드에서 /images/hero.png로 부르면 어떤 환경에서는 깨집니다. 큰 이미지가 깨지는 것만으로 끝나지 않고, 이미지 크기를 기준으로 레이아웃을 잡는 코드가 함께 멈추면 흰 화면처럼 보일 수 있습니다.

6. window, document, localStorage 사용 위치를 본다

Next.js에서는 서버에서 먼저 화면을 만들고 브라우저에서 이어받는 과정이 있습니다. 이때 컴포넌트 최상단에서 window, document, localStorage를 바로 읽으면 배포 빌드나 초기 렌더링에서 문제가 생길 수 있습니다.

대표 증상은 이렇습니다.

• window is not defined
• document is not defined
• Hydration failed
• 로컬 개발 모드에서는 되는데 npm run build에서만 실패

브라우저에서만 필요한 값은 useEffect 안에서 읽거나, 클라이언트 컴포넌트 안으로 분리해야 합니다. AI가 빠르게 화면을 만들 때 자주 놓치는 경계입니다.

7. 특정 경로만 비면 라우팅과 정적 배포 방식을 본다

홈은 뜨는데 /dashboard, /login 같은 경로만 흰 화면이라면 라우팅 문제일 수 있습니다.

확인할 것:

• 해당 페이지 파일이 실제로 존재하는가
• 동적 route가 정적 export 방식과 충돌하지 않는가
• 로그인 보호 로직이 리다이렉트 무한 루프를 만들지 않는가
• Vite/React SPA라면 새로고침 시 fallback 설정이 필요한가

특히 AI로 만든 프로젝트에서는 처음에는 단순 정적 사이트였다가 로그인, 관리자, API가 섞이면서 배포 방식과 코드 구조가 맞지 않게 되는 경우가 있습니다.

정리

Vercel 배포 후 흰 화면이 뜰 때는 아래 순서로 보면 됩니다.

1. 배포 빌드가 성공했는지 확인한다
2. 브라우저 콘솔의 첫 번째 에러를 본다
3. 환경 변수가 Vercel에 등록되어 있는지 확인한다
4. localhost나 예전 주소가 남아 있는지 검색한다
5. 파일 경로와 이미지 경로의 대소문자를 맞춘다
6. window, document, localStorage 사용 위치를 본다
7. 특정 경로만 문제라면 라우팅과 배포 방식을 확인한다

흰 화면은 겉으로는 하나의 증상이지만, 원인은 여러 갈래입니다. 플랫폼을 바꾸기 전에 첫 에러부터 잡으면 시간을 훨씬 줄일 수 있습니다.

관련 글: Vercel과 Netlify 차이점, Vercel 환경변수가 적용 안 될 때, 비개발자가 점검할 5가지, AI가 만든 서비스인데 배포 후 안 되는 이유 TOP 10