[TypeScript]React 개발 프로젝트에서 BrowserRouter를 사용했을 때 화면이 정상적으로 렌더링되지 않는 경우 + Vite(트러블 슈팅)

원인 : React로 프로젝트를 개발하다 보면, BrowserRouter를 사용했을 때 화면이 정상적으로 렌더링되지 않는 경우가 있습니다. 하지만 HashRouter로 변경하면 문제없이 동작하는데 그 이유를 알아보자.

 

BrowserRouter 를 사용하면 화면이 안 나오는 이유

 

BrowserRouter는 history API를 활용하기 때문에, 사용자가 새로고침을 하면 문제가 발생할 수 있습니다.
일반적으로 React 애플리케이션은 단일 HTML 파일(index.html)을 기반으로 동작합니다. 그런데 BrowserRouter를 사용할 경우, 새로고침을 하면 해당 경로(/about 등)에 대한 요청이 서버로 직접 전달됩니다.

이는 개발 서버(Vite, Webpack Dev Server 등)가 해당 URL을 인식하지 못하기 때문입니다.

HashRouter를 사용하면 해결되는 이유

 

HashRouter는 URL의 # 뒤쪽을 클라이언트에서만 사용하기 때문에, 새로고침해도 서버로 요청이 전달되지 않습니다.
즉, 서버 설정 없이도 문제없이 작동합니다.

import { HashRouter, Route, Routes } from 'react-router-dom';

<HashRouter>
  <Routes>
    <Route path="/" element={<App />} />
  </Routes>
</HashRouter>

 

이렇게 하면 /about 페이지로 이동해도 URL이 http://localhost:5173/#/about 형태가 되어,
서버에서 404 에러를 발생시키지 않고 정상적으로 동작합니다.