왜 내 React 앱이 GitHub Pages에 배포한 후 흰 화면을 표시했을까

Source: Dev.to

혼란스러웠던 상황

React 프로젝트를 GitHub Pages에 배포했을 때, 개발 중에는 모든 것이 정상적으로 보였습니다.
배포 후 페이지를 열어보니 완전히 흰 화면만 보였고—오류도 보이지 않았습니다.

브라우저 콘솔을 확인해 보니 JavaScript와 CSS 파일이 로드되지 않고 있었습니다. URL은 다음과 같은 형태였습니다:

/assets/index.js
/assets/index.css

처음엔 이것이 일반적인 로컬 경로라고 생각했습니다. 간단한 HTML 프로젝트에서는 다음과 같이 사용합니다:

assets/index.js

그리고 호스팅했을 때도 정상적으로 작동했습니다. 그렇다면 왜 이 경우는 실패했을까요?

발견한 문제

문제는 바로 앞에 붙은 슬래시 /였습니다. / 로 시작하는 경로는 브라우저에 다음과 같이 지시합니다:

“도메인의 루트부터 검색을 시작하라.”

즉,

username.github.io/my-project/

안이 아니라

username.github.io/

부터 찾게 됩니다. 그래서 브라우저는 다음을 로드하려고 시도했습니다:

username.github.io/assets/index.js

하지만 실제 파일은 다음 위치에 있었습니다:

username.github.io/my-project/assets/index.js

파일을 찾지 못해 흰 화면이 나타난 것입니다.

로컬에서는 왜 정상 작동했을까?

로컬 HTML 프로젝트에서는 다음과 같이 사용했습니다:

assets/index.js

이는 상대 경로이며, 브라우저에 다음을 알려줍니다:

“현재 폴더부터 검색을 시작하라.”

그래서 로컬에서도, 배포 후에도 정상적으로 동작한 것입니다.

교훈

경로에는 세 가지 유형이 있습니다:

• 절대 URL →
• 루트‑상대 → /file.js
• 상대 → file.js 또는 ./file.js

앞에 슬래시 /가 붙은 경로는 로컬 경로가 아니라 루트‑상대 경로입니다. 이 작은 차이 때문에 전체 배포가 망가졌습니다.