Vercel 배포 성공인데 404가 뜰 때 점검법

Vercel 대시보드에는 배포가 Ready로 보이는데 링크를 열면 404: NOT_FOUND가 뜰 수 있다. 이때 다시 배포하거나 vercel.json을 복사하기 전에 같은 배포의 기본 URL과 문제가 난 경로를 따로 열어야 한다. 배포 성공은 빌드 작업이 끝났다는 뜻이지, 모든 URL과 도메인이 올바르게 연결됐다는 증거는 아니다.

먼저 <배포이름>.vercel.app/과 실제로 열려던 /dashboard 같은 경로를 각각 확인한다. 그 결과를 “모두 404”, “하위 경로만 404”, “커스텀 도메인만 404”, “특정 사람·네트워크만 404” 중 하나로 적으면 고칠 범위가 줄어든다. 원인 범위를 적기 전에는 설정을 바꾸지 않는 것이 첫 안전장치다.

첫 1분에는 404가 어디서 재현되는지 나눈다

Vercel의 배포 성공 후 404 공식 가이드는 잘못된 URL과 접근 권한, 프로젝트 설정, Output Directory, SPA rewrite, 로그를 서로 다른 점검 항목으로 둔다. 화면은 같아도 원인은 하나가 아니다.

아래 네 칸을 순서대로 확인한다.

기본 배포 URL의 /도 404인가? 그렇다면 하위 경로 라우팅보다 Framework Preset, Root Directory, Output Directory를 먼저 본다.
/은 열리고 주소창에 하위 경로를 직접 넣거나 새로고침할 때만 404인가? 클라이언트 라우터를 쓰는 SPA의 fallback 여부를 확인한다.
vercel.app 주소는 열리고 커스텀 도메인만 404인가? 코드보다 프로젝트의 도메인 할당과 DNS 상태를 본다.
내 계정이나 특정 네트워크에서만 다른가? Deployment Protection, 팀 권한, Trusted IP 같은 접근 조건을 확인한다.

404 화면에 Code와 ID가 함께 보이면 그것도 복사한다. Vercel 404 디버깅 문서는 화면의 오류 코드 설명을 먼저 확인하고, 이후 도메인·접근 권한·프로젝트 설정·로그로 범위를 좁히도록 안내한다.

설정 네 곳은 현재값을 적고 하나씩 비교한다

문제 범위를 나눴다면 Project Settings의 Build and Deployment에서 Framework Preset, Root Directory, Output Directory, rewrite 네 곳을 본다. 한꺼번에 바꾸면 어떤 수정이 효과가 있었는지 알 수 없다.

Framework Root Output Rewrite 네 설정을 현재값과 기대값으로 비교하는 체크리스트

Framework Preset

Next.js 프로젝트라면 Vercel이 Next.js를 감지했는지 확인한다. Vercel 빌드 설정 문서에 따르면 지원 프레임워크가 감지되면 프레임워크에 맞는 설정과 출력 경로가 자동 구성된다. AI가 만든 저장소를 가져온 뒤 Preset이 Other로 남았거나 수동 override가 켜져 있다면 기본 동작과 달라질 수 있다.

Next.js인데 하위 경로가 404라고 해서 곧바로 SPA용 catch-all rewrite를 넣지는 않는다. Next.js는 자체 파일 기반 라우팅을 사용하므로 먼저 app/dashboard/page.tsx 또는 pages/dashboard.tsx처럼 요청 경로에 대응하는 route가 실제 배포 커밋에 있는지 본다. API 주소에서만 404나 405가 난다면 Next.js API 주소와 메서드를 나누는 점검법으로 문제를 더 좁힐 수 있다.

Root Directory

모노레포나 상위 폴더에 여러 앱이 있으면 Vercel이 어느 폴더에서 설치와 빌드를 시작하는지가 중요하다. 앱의 package.json과 next.config.*가 apps/web 안에 있다면 Root Directory도 그 앱 경로를 가리켜야 한다. Vercel 공식 문서는 Root Directory 밖의 파일에는 앱이 접근할 수 없고, 설정 변경은 다음 배포부터 적용된다고 설명한다.

확인할 값은 단순하다.

선택한 Root Directory 안에 실제 앱의 package.json이 있는가?
Build Logs의 첫 경로가 내가 기대한 앱 폴더인가?
최근 저장소 구조 변경 뒤 예전 Root Directory가 남아 있지 않은가?

Output Directory

Output Directory를 수동으로 덮어썼다면 빌드는 성공해도 Vercel이 비어 있거나 엉뚱한 폴더를 제공할 수 있다. Vercel의 404 가이드는 성공 배포 404에서 가장 가능성 높은 설정 오류로 Output Directory를 짚는다.

프레임워크 기본값을 쓰는 프로젝트라면 이유 없이 dist, build, out을 입력하지 않는다. 실제 빌드 명령이 만드는 폴더와 Vercel이 제공하도록 지정한 폴더가 같은지 비교한다. Next.js Preset을 정상 사용한다면 임의의 정적 폴더 override를 지우고 프레임워크 기본 설정으로 돌아가는 편이 우선이다.

Rewrite

React Router 같은 클라이언트 라우터를 쓰는 SPA에서 /은 열리지만 /dashboard 직접 접속만 404라면 서버가 해당 경로에 대응하는 파일을 찾지 못한 상황일 수 있다. 프로젝트 유형을 확인한 뒤에만 다음과 같은 SPA fallback을 검토한다.

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Vercel rewrite 공식 문서는 같은 앱 안의 rewrite를 프레임워크가 네이티브 라우팅을 제공하지 않을 때 사용하라고 안내한다. 따라서 Next.js 프로젝트에 이 설정을 무조건 붙이는 것은 해결 순서가 아니다. 기존 vercel.json에 넓은 rewrite가 이미 있다면 새 규칙을 더하기 전에 그 규칙이 정상 route까지 가로채는지도 확인한다.

원인별로 한 가지만 수정하고 새 배포를 만든다

진단 결과에 맞는 최소 수정만 선택한다.

재현 범위	먼저 고칠 후보	수정 뒤 확인
기본 URL부터 모두 404	Framework Preset, Root Directory, Output Directory	다음 배포의 Build Logs와 `/`
SPA의 하위 경로 직접 접속만 404	SPA fallback rewrite	`/`, 링크 이동, 하위 경로 새로고침
Next.js 특정 경로만 404	route 파일·폴더 이름, 배포된 커밋	해당 경로 직접 접속과 링크 이동
커스텀 도메인만 404	프로젝트 할당, Valid Configuration, DNS	`vercel.app`과 커스텀 도메인 비교
일부 사용자만 404	Deployment Protection, 권한, Trusted IP	로그아웃 창과 허용 네트워크 비교

커스텀 도메인만 문제라면 Vercel 도메인 문제 해결 문서에 따라 그 도메인이 해당 프로젝트에 추가됐는지, 안내된 A 또는 CNAME 레코드를 가리키는지 확인한다. 도메인과 프로젝트 할당 문서는 Project Settings의 Domains에서 연결하며, 일반적으로 그 도메인이 프로젝트의 최신 Production Deployment를 제공한다고 설명한다.

설정 하나를 바꿨다면 새 배포가 필요하다. 이전 배포 URL을 계속 열면 수정 결과를 보지 못한다. 배포가 실패 상태로 바뀌었다면 404 점검을 계속하지 말고 Vercel 배포 로그에서 멈춘 지점을 찾는 순서로 전환한다.

재배포 뒤에는 성공 배지보다 네 주소를 검증한다

새 배포가 Ready가 되면 다음 네 주소를 각각 새 탭이나 시크릿 창에서 연다.

새 배포의 기본 vercel.app/
문제가 났던 하위 경로를 주소창에 직접 입력한 URL
앱 안의 링크를 눌러 이동한 같은 하위 경로
연결된 커스텀 도메인의 같은 경로

그다음 Build Logs에서 앱 폴더와 출력 경로를, Runtime Logs에서 요청 시점의 오류를 확인한다. 기본 URL과 하위 경로가 모두 200으로 열리고, 새로고침 뒤에도 같은 화면이 유지되며, 커스텀 도메인까지 같은 배포를 보여야 완료다.

여기까지 확인해도 404라면 화면의 Code와 ID, 문제 URL, 배포 ID, 재현 범위, 현재 Framework·Root·Output·Rewrite 값을 한 번에 모은다. 이 다섯 묶음이 있어야 팀 관리자나 Vercel 지원 문서에서 다음 원인을 빠르게 찾을 수 있다. 오늘은 기본 URL과 문제 경로를 비교해 한 갈래를 고르고, 설정 하나만 바꾼 뒤 같은 네 주소로 재검증하면 된다.

참고 출처

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.

Vercel 배포 성공인데 404, 루트·하위 경로별 점검표