Vercel 배포는 됐는데 새로고침만 404라면, SPA rewrite를 확인하세요

홈 화면에서 메뉴를 눌러 /dashboard로 가면 잘 열린다. 그런데 그 주소를 새 탭에 붙여 넣거나 새로고침하면 Vercel의 404: NOT_FOUND가 뜬다. 이때 React 컴포넌트부터 다시 고치면 같은 배포를 반복하기 쉽다.

결론부터 말하면 링크 이동은 되고 하위 경로 직접 접근만 404라면, 먼저 정적 클라이언트 SPA인지 확인해야 한다. SPA가 맞다면 Vercel이 하위 URL 요청을 앱의 진입 HTML로 넘기도록 fallback rewrite를 둔다. Next.js처럼 서버가 경로를 처리하거나 React Router를 프레임워크 모드로 배포했다면 같은 설정을 무조건 복사하지 않는다.

Tap to zoom

홈·링크 이동만 되고 직접 접근이 404면 Vite SPA 확인 뒤 /index.html로 넘긴다

링크를 눌렀을 때는 이미 내려받은 JavaScript와 React Router가 브라우저 안에서 화면을 바꾼다. 반면 주소창 직접 접근과 새로고침은 Vercel 서버에 /dashboard 문서를 새로 요청한다. 서버가 그 경로에 대응하는 파일이나 서버 라우트를 모르면 404를 돌려준다.

Vercel의 404 공식 안내는 플랫폼이 URL을 서버가 해석할 경로로 다루며, 단일 페이지 앱(SPA)은 클라이언트 라우터에 넘길 rewrite가 필요하다고 설명한다. React Router의 SPA 안내도 정상 앱 경로에서 404가 나면 호스트가 모든 URL을 index.html로 보내도록 설정했는지 확인하라고 안내한다.

아래 세 조건이 함께 맞으면 SPA fallback 문제일 가능성이 높다.

• 홈 /은 열린다.
• 앱 안의 링크로 /dashboard에 가면 열린다.
• /dashboard를 직접 열거나 새로고침할 때만 Vercel 404가 뜬다.

홈부터 404이거나 CSS·JavaScript 파일만 404라면 다른 문제다. Vercel 프로젝트의 Root Directory, Build Command, Output Directory부터 확인한다. 배포가 과거 커밋을 보고 있는지는 Vercel에서 이전 화면이 보일 때 브랜치와 캐시를 확인하는 순서로 따로 좁힐 수 있다.

Tap to zoom

정적 SPA라면 rewrite로 앱 라우터에 넘긴다

Vite로 만든 React 앱을 정적 SPA로 배포하고 있다면 Vercel 프로젝트 루트에 vercel.json을 둔다. 모노레포에서는 저장소 최상단이 아니라 Vercel 설정의 Root Directory가 기준이다.

설정의 핵심은 한 줄이다.

• 파일: vercel.json
• rewrite: { "source": "/(.*)", "destination": "/index.html" }

Vercel 공식 예시는 모든 경로 요청을 SPA 진입 파일로 보내 클라이언트 라우터가 최종 화면을 고르게 한다. 기존 vercel.json이 있다면 덮어쓰지 말고 현재 rewrites, redirects, Functions 경로와 충돌하지 않는지 먼저 읽는다. API 경로까지 무조건 진입 HTML로 보내면 JSON 대신 HTML이 돌아올 수 있다.

파일을 저장하고 Git에 반영한 뒤 새 Preview 배포를 만든다. 설정을 추가한 커밋이 실제 배포 대상 브랜치에 포함됐는지 배포 상세에서 확인한다. 환경변수 때문에 Preview만 실패한다면 Next.js 환경변수가 배포에서 undefined일 때 확인할 순서를 함께 본다.

성공 표시는 홈이 아니라 하위 URL에서 확인한다

Vercel 대시보드의 Ready 표시는 빌드와 배포가 끝났다는 뜻이지 모든 앱 경로가 작동한다는 보장은 아니다. 새 Preview URL이 나오면 홈보다 실패했던 하위 경로를 먼저 검사한다.

1. 새 시크릿 창에 https://<preview-domain>/dashboard를 직접 붙여 넣는다.
2. 화면이 뜨면 같은 경로에서 새로고침한다.
3. 개발자 도구 Network에서 Type이 document인 요청의 Status가 200인지 본다.
4. 화면은 떴지만 데이터가 비었다면 API 요청의 401·404·500을 별도로 확인한다.

직접 접근과 새로고침이 모두 통과해야 수정 완료다. 홈에서 링크 한 번 누른 결과만으로 끝내지 않는다. Vercel의 404 디버깅 문서는 오류 코드뿐 아니라 Root Directory와 설정 파일의 rewrite도 함께 점검하라고 안내한다.

Tap to zoom

Next.js와 React Router 프레임워크 모드에는 그대로 복사하지 않는다

이 rewrite는 정적 클라이언트 SPA의 fallback이다. Next.js는 파일·앱 라우터와 서버 렌더링 규칙이 있고, React Router를 프레임워크로 쓰는 앱도 서버 렌더링이나 SPA mode 빌드 구성이 따로 있다. Vercel의 React Router 공식 문서는 현재 Vercel preset을 권장하며 프레임워크 배포 경로를 별도로 제공한다.

따라서 package.json의 빌드 도구와 라우터 구성을 먼저 확인한다.

• Vite 정적 React 앱과 BrowserRouter: SPA fallback rewrite 후보
• Next.js App Router 또는 Pages Router: Next.js 라우트와 배포 로그부터 확인
• React Router 프레임워크 모드: Vercel preset과 해당 빌드 출력 설정 확인

오늘 남길 결과는 설정 파일 자체가 아니다. 새 Preview의 하위 URL을 직접 열고 새로고침해 같은 화면과 HTTP 200을 확인한 상태다. 이 결과가 남아야 배포가 실제 사용자 진입 경로까지 통과한 것이다.

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

참고 출처

• Vercel: Why is my deployed project showing a 404 error?
• Vercel: How to debug 404 errors
• Vercel: React Router on Vercel
• React Router: Single Page App (SPA)