React 개발 중 새로 추가한 페이지에서 새로고침 시 404 오류가 발생한 이유 (feat. proxy 설정의 함정)

나를 무려 이틀 반동안 골치아프게했던 문제가 해결되었다.

생각보다 너무 어이없는 이유라서 티스토리에도 기록을 남겨본다..

 

✅ 문제 상황

React + Express로 개발 중, 새로운 메뉴를 추가해야만 했다.

프론트 라우터에 새로운 경로를 등록했고, 백엔드에도 해당 API 및 미들웨어를 잘 붙여놨다.

그런데 문제는...메뉴를 직접 클릭해서 이동하면 잘 되는데, 새로고침만 하면 ENOENT: no such file or directory가 발생하는 것!

Error: ENOENT: no such file or directory, stat '...경로...\client\index.html'

 

 

🔍 문제 원인을 찾아서

'spa 새로고침 404'로 검색하니 SPA 라우팅 문제라고 곧잘 내용이 정리되어있었다.

Spring Boot&React에서 새로 고침 404 오류 해결 방법

 

웹팩 환경에서 React Router 새로고침 했을 때 404에러 해결하는 방법

 

proxy 설정을 해두면 Dev Server는 /api로 시작하는 요청만 백엔드로 넘김

→  /api/.../...는 내부 라우터에서 없음

→ 404에러를 발생

이 루트로 404 에러를 만나게 되는 것이었고, 주로 해결책으로 발견된 건 아래의 세가지였다.

 

• historyApiFallback: true 
  → historyApiFallback는 이미 잘 설정이 되어있었다.
• Express 서버에서 모든 요청에 대해 index.html 반환 
  → index.html을 반환하는것도 서버 코드만 있는 레포지토리다 보니 로컬 상황에선 맞지 않았다.
• react-router-dom의 BrowserRouter에서 HashRouter 대체
  → 고쳐지긴 했지만, 프레그먼트가 붙는게 사용자 입장에서 별로 안좋을 것 같았고 문제의 근본적인 원인을 해결하지 못하는 것 같았다.

 

 

아무리 gpt를 뚜드려 혼내도 계속 historyApiFallback 문제라고 하길래 진짜 답답해 돌아버리는 줄 알았는데...🤯

문제는 proxy 설정이었다.

 

내 프론트의 package.json에는 다음과 같은 proxy 설정이 있었다:

"proxy": "/api"

 

그리고 내가 추가한 메뉴의 라우트는 '/apiExample'이었다. (ㅋ...)

 

React Dev Server의 proxy 기능은 내부적으로 http-proxy-middleware를 사용하는데,

이 라이브러리는 context 매칭을 startsWith() (혹은 구버전은 indexOf(context) === 0)로 처리한다.

http-proxy-middleware의 context-matcher

 

즉,

"/apiexample".startsWith("/api") === true

가 되어버려서 /apiexample도 /api로 매칭되었다고 판단되어
존재하지 않는 Express 경로로 요청을 보내서 결국 404가 터진 것...

 

 

문제 해결.

해결은 간단했다. proxy 설정의 '/api'를 '/api/'로 바꾸어주었다...^^....ㅠ

이렇게 해주면 /apiexample은 프록시 대상에서 제외된다. 이후 새로고침 문제도 말끔하게 사라졌다 하핫!!!!!!!

 

혹시 나처럼 404의 늪에 빠져있는 누군가가 있다면 proxy설정과 라우트 경로를 확인해보길 바라며....🙏