vercel 배포 오류 - 새로고침 404: NON_FOUND

문제 상황

vercel에서 github를 연동하여 main 브랜치의 내용을 배포하였다.

모든 기능이 잘 작동하지만 페이지를 새로고침 시 404 에러가 떴다.

 

 

오류 해결 시도

 

📍시도 1 : route path="/*" 설정

Home, Dex, Detail 루트 외에도 그 외 다르게 입력되는 모든 주소의 접근을 "/*" 로 처리해주었다.

 

path="/*" (정의되지 않은 모든 경로를) element={<Home />} /> (Home 컴포넌트로 돌아가도록 처리)

1️⃣ path="/*"

 

• path="/*"는 **모든 경로를 포함하는 "와일드카드(Wildcard) 경로"**를 의미한다.
• 즉, 정의되지 않은 경로(404 페이지) 또는 모든 하위 경로를 처리하는 데 사용된다.
• 주로 404 Not Found 페이지나 특정 패턴을 가진 페이지의 하위 라우트 처리에 활용된다.

2️⃣ 특정 경로 하위에서만 /* 사용 시

• 하위 경로에서의 404 페이지를 만들 수 있다.
• <Route path="/dashboard/*" element={<NotFound />} />   👉🏻 대시보드 내부 404 처리
• /dashboard/other-page (정의되지 않은 경로)  👉🏻NotFound 컴포넌트

 

const Router = () => {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/dex" element={<Dex />} />
        <Route path="/detail" element={<Detail />} />
        <Route path="/*" element={<Home />} />
      </Routes>
    </BrowserRouter>
  );
};

 

 

📍시도 2 : element와 import 확인

path에 연결된 element 페이지를 살펴보고 사용하지 않는 import를 정리했다.

 

 

 

오류 해결 방법

 

📍vercel.json 으로 프로젝트 구성하기

구글링을 통해 알게 된 vercel.json 으로 프로젝트 구성하기

https://vercel.com/docs/projects/project-configuration#buildcommand

 

사이트 내에는 다양한 json 파일 사용방법이 있다.

그 중 rewrites 를 살펴보면

한국어로 변역한 페이지

 

source의 경로를 destination의 경로로 다시 작성해주는 듯하다.

 

이 오류의 원인은 Vercel의 정적 파일 서비스 방식 때문인데 자세한 내용은 아래 접은 글을 참고하면 좋을 듯 하다.

문제 원인: Vercel의 정적 파일 서비스 방식

 

👉 React Router는 "클라이언트 사이드 라우팅(Client-Side Routing)"을 사용
👉 하지만 Vercel은 "정적 파일 기반의 서버 라우팅(Server-Side Routing)"을 사용
👉 /about 페이지에서 새로고침하면, Vercel은 /about/index.html을 찾지만, 존재하지 않으므로 404 오류 발생

 

✅ 즉, React Router는 index.html 하나로 모든 라우트를 처리하는데, Vercel은 이를 모르기 때문에 새로고침 시 404 오류가 발생합니다.

 

 

📌아무튼 오류 해결 방법은 다음과 같다.

• src와 동일한 선상에서 vercel.json 파일 생성
• 파일 내에 아래 로직 작성 (Vercel이 모든 경로를 index.html로 리디렉트하도록 설정)
  • "/(.*)" → 모든 경로를 의미 (정규식)
  • destination: "/index.html" → 요청된 모든 경로를 index.html로 리디렉트
• add, commit, push, PR을 통해 배포 사이트에 적용

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

 

---

참고 자료 :

velog

vercel