[PeaNutter] Vercel 배포 시 하위 라우터 404 오류 해결

문제 상황

Vercel로 프로젝트를 배포한 후, '/profile/edit'과 같은 하위 라우터에서 새로고침을 하니 404 Not Found 오류가 발생했다.

 

원인 분석

SPA와 전통적인 웹 애플리케이션의 차이

전통적인 웹 애플리케이션

사용자가 각 페이지에 접근할 때마다 서버에서 해당 페이지의 HTML을 제공한다.

'/posts', '/profile' 등의 페이지를 요청하면, 서버는 각각의 요청에 맞는 HTML 파일을 찾아서 보내주는 방식이다.

 

싱글 페이지 애플리케이션(SPA)

초기 접근 시 단 하나의 HTML 파일인 index.html을 로드하고, 그 이후의 모든 페이지 전환은 브라우저에서 JavaScript를 사용하여 동적으로 내용을 변경한다.

사용자가 '/profile/edit' 같은 URL로 이동하더라도 실제로는 index.html에서 처리되며, 서버에는 '/profile/edit'를 위한 별도의 HTML 파일이 존재하지 않는다.

 

404 오류 발생 원인

SPA를 서버에 배포했을 때, 사용자가 직접 '/profile/edit' 같은 경로를 브라우저에서 요청하면 서버는 해당 경로에 대응하는 HTML 파일을 찾으려고 시도한다. 하지만 SPA에서는 index.html 파일만 존재하기 때문에 서버는 '/profile/edit'에 대한 리소스를 찾을 수 없어 404 오류를 반환한다.

클라이언트: 프로필 수정 페이지로 가자!
서버: 프로필 수정 페이지 파일 없는데? index.html밖에 없어. 그런 파일 몰라 나는..

 

해결 방안

모든 서버 요청을 SPA의 진입점인 index.html로 리디렉션하도록 서버 설정을 변경해야 한다.

어떤 URL로 접근하든 서버는 항상 index.html을 제공하고, 페이지의 실제 라우팅은 브라우저가 JavaScript를 이용해 처리하게 된다.

Vercel 설정

Vercel에서는 vercel.json 파일을 사용해 리디렉션을 설정할 수 있다.

{
  "rewrites": [{ "source": "/(.*)", "destination": "/" }]
}

rewrites 규칙을 추가하여 어떤 경로로 요청이 들어와도 항상 index.html로 요청을 보내도록 설정했다.

 

이 설정 후 Vercel 서버는 모든 요청을 index.html로 포워딩하여 클라이언트 측에서 정상적인 라우팅을 수행할 수 있게 되었고, 하위 라우터에서 새로고침을 하더라도 더 이상 404 오류가 발생하지 않았다.