[React] Netlify 배포 후 새로고침 시 404 에러 해결하기

React 프로젝트를 Netlify에 배포한 뒤 정상적으로 화면 이동은 되지만,
특정 페이지에서 새로고침을 하면 404 에러가 발생하는 문제가 있었다.

예를 들어 아래와 같은 URL에 직접 접속하거나 새로고침을 하면

https://my-site.netlify.app/login

Netlify에서 Page Not Found를 반환하였다.

---

문제 원인

React Router는 클라이언트 사이드 라우팅(Client-Side Routing)을 사용한다.

즉, 브라우저에서 URL이 변경되더라도 실제로는 React가 페이지 전환을 처리하며, 서버에는 새로운 페이지 요청이 전달되지 않는다.

하지만 사용자가 특정 경로로 직접 접속하거나 새로고침을 수행하면 상황이 달라진다.

/
├── login
├── community
└── mypage

React는 /login 페이지를 알고 있지만,
Netlify 서버는 실제로 /login이라는 파일이 존재한다고 생각하고 해당 파일을 찾게 된다.

결과적으로 서버는 해당 파일을 찾지 못해 404 에러를 반환하게 된다.

---

해결 방법

Netlify에 모든 요청을 index.html로 전달하도록 설정하면 해결할 수 있다.
React Router가 이후 URL을 해석하여 올바른 페이지를 렌더링하게 된다.

방법 1. _redirects 파일 사용

프로젝트의 public 폴더 또는 배포 루트에 _redirects 파일을 생성한다.

/*    /index.html   200

이 설정은 모든 요청을 index.html로 전달한다는 의미이다.

방법 2. netlify.toml 파일 사용

프로젝트 루트에 netlify.toml 파일을 생성한다.

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

마찬가지로 모든 경로 요청을 index.html로 전달하는 설정이다.

---

결과

설정을 적용한 후에는

/
/login
/community
/mypage

어느 경로에서 새로고침을 하더라도 정상적으로 페이지가 표시된다.

React Router를 사용하는 SPA(Single Page Application)를 Netlify에 배포할 경우 거의 필수적으로 적용해야 하는 설정 중 하나였다.

Reference

Netlify "page not found" 오류 해결 방법
[netlify] Page Not Found Error (React Router)