[Git] React를 Git Pages에 호스팅 할 때 404 만 뜨는 문제
React 프로젝트를 Git Pages에 호스팅 했다.
단일 페이지일 때는 잘만 되더니 Router를 걸어놓으니까 계속 404만 떴다.
원인은 내가 사용한 BrowserRouter 라이브러리 때문이었는데
결론말 말하면 BrowerRouter -> HashRouter로 바꿔주면 해결된다.
📌 BrowserRouter vs HashRouter 차이
1️⃣ BrowserRouter (기본)
BrowserRouter는 HTML5의 History API(pushState, replaceState)를 사용하여 URL을 조작하는 방식
import { BrowserRouter as Router } from 'react-router-dom'; function App() { return ( <Router> {/* 라우트 설정 */} </Router> ); }❌ GitHub Pages에서는 이 방식이 문제를 일으킴!
GitHub Pages는 정적인 파일만 제공하므로 서버가 없고, 404 오류가 발생
즉, 사용자가 URL로 직접 접근하면 서버가 없어서 about을 찾을 수 없고, 404 오류가 발생!
2️⃣ HashRouter (GitHub Pages에서 최적)
HashRouter는 URL에 #을 포함시켜 브라우저가 서버 요청을 보내지 않고 클라이언트에서 라우팅하도록 만든다.
import { HashRouter as Router } from 'react-router-dom'; function App() { return ( <Router> {/* 라우트 설정 */} </Router> ); }👉 URL 예시 (HashRouter 사용)
✅ GitHub Pages에서 정상 작동!
- 브라우저는 # 뒤의 경로를 서버로 보내지 않고 클라이언트에서 처리함.
- 서버는 항상 index.html을 제공하고, React가 #/about을 보고 올바른 컴포넌트를 렌더링.
- 새로고침해도 서버는 index.html을 서빙하고, React가 다시 렌더링!
- 404 오류 없음!
📌 정리: 왜 HashRouter를 쓰면 해결됨?
BrowserRouter (❌ GitHub Pages에서 문제) vs HashRouter (✅ GitHub Pages에서 최적)| 라우팅 방식 | pushState 사용 (서버 필요) | window.location.hash 사용 (서버 불필요) |
| URL 구조 | /about | /#/about |
| 새로고침 시 서버 요청 | ❌ /about을 찾으려다 404 발생 | ✅ index.html만 요청하고 클라이언트에서 라우팅 |
| GitHub Pages에서 작동 여부 | ❌ 404 오류 발생 | ✅ 정상 작동 |
🚀 GitHub Pages 같은 정적 호스팅에서는 HashRouter를 사용하면 404 오류가 발생하지 않음! 🚀
📌 BrowserRouter를 꼭 사용하고 싶다면?
만약 BrowserRouter를 유지하고 싶다면 GitHub Pages에서 모든 요청을 index.html로 리디렉트하는 설정이 필요하다.
1️⃣ public/404.html 추가:
<!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="refresh" content="0; url=./" /> </head> <body> </body> </html>
2️⃣ public/_redirects 추가 (Netlify 사용 시)
/* /index.html 200✅ 이렇게 하면 GitHub Pages가 404 발생 시 자동으로 index.html을 서빙하고, React가 올바르게 라우팅함.
하지만 GitHub Pages 기본 설정으로는 이 방법이 안 되므로 HashRouter가 가장 쉬운 해결책!
💡 결론
👉 GitHub Pages에서 BrowserRouter를 사용하면 서버가 없어서 404가 발생함.
👉 HashRouter를 사용하면 # 이후의 URL을 브라우저가 처리하므로 서버 요청 없이 정상 작동! 🚀