Github Pages 새로고침시 404 에러 발생 문제

Jongmyung Choi·2023년 12월 19일

개요

포트폴리오 프로젝트를 Github Pages를 통해 배포를 진행했는데 새로고침 시 404에러 가 발생하였다.

문제 원인

GitHub Pages를 사용하여 개인 도메인으로 사이트를 배포할 때 새로고침 시 리다이렉트가 제대로 작동하지 않는 문제는 SPA의 라우팅 문제 때문에 발생한다.

SPA에서는 브라우저의 새로고침이나 직접 URL 입력 시 서버에서 해당 경로에 대한 HTML 파일을 제공하지 않기 때문에 404 에러가 발생할 수 있다고 한다.

문제 해결

이를 해결하기 위한 방법으로는 크게 2가지가 있다.

HashRouter 이용

HashRouter는 React Router의 한 종류로, 클라이언트 사이드 라우팅을 위해 URL의 해시(#) 부분을 사용한다.
gh-pages 에서도 이를 권장한다.

자세한 설명은 생략하고 HashRouter를 사용하지 않은 이유는 다음과 같다.

SEO 최적화의 어려움
해시를 사용하는 URL은 검색 엔진 최적화(SEO)에 불리하다. 대부분의 검색엔진은 해시를 사용하는 URL을 적절하게 크롤링하거나 색인화하지 못하기 때문이다.
URL의 직관성
URL에 #이 들어가기 때문에 먼가 깔끔하지 않다. 🥲

404 페이지 이용

gh-pages에서 존재하지 않는 경로에 대해 404.html 파일을 제공하는 걸 역으로 이용하는 방법이 있다. ~~(꼼수)~~

1.404.html 사용

build 폴더 안에 index.html 파일의 복사본을 public 폴더 안에 404.html로 만든다.
이렇게 하면 사용자가 존재하지 않는 경로로 이동할 때 404.html이 로드되고, SPA 라우팅 로직이 해당 URL을 처리하여 올바른 페이지로 이동시킨다.

2.Custom SPA 라우팅 규칙 적용

GitHub Pages에서는 직접 서버 설정을 변경할 수 없으므로, 자바스크립트를 사용하여 SPA 라우팅을 수동으로 처리할 수 있다.
404.html에서 아래와 같은 코드를 추가한다.

<head>
	<script type="text/javascript">
			// Single Page Apps for GitHub Pages
			// https://github.com/rafrex/spa-github-pages
			// Copyright (c) 2016 Rafael Pedicini, licensed under the MIT License
			// ----------------------------------------------------------------------
			// This script checks to see if a redirect is present in the query string
			// and converts it back into the correct url and adds it to the
			// browser's history using window.history.replaceState(...),
			// which won't cause the browser to attempt to load the new url.
			// When the single page app is loaded further down in this file,
			// the correct url will be waiting in the browser's history for
			// the single page app to route accordingly.
			(function (l) {
				if (l.search) {
					var q = {};
					l.search
						.slice(1)
						.split("&")
						.forEach(function (v) {
							var a = v.split("=");
							q[a[0]] = a
								.slice(1)
								.join("=")
								.replace(/~and~/g, "&");
						});
					if (q.p !== undefined) {
						window.history.replaceState(
							null,
							null,
							l.pathname.slice(0, -1) +
								(q.p || "") +
								(q.q ? "?" + q.q : "") +
								l.hash
						);
					}
				}
			})(window.location);
	</script>
 </head>