GitHub Pages 배포 후 CSS가 안 먹힌다? 67세 교수의 3시간 삽질기

나의 첫 GitHub Pages 배포 시도 - 희망 찬 출발

작년 정년을 앞두고 있는 67세의 컴퓨터공학과 교수인 나는, 그동안 연구해온 내용들을 정리하는 블로그를 만들고 싶었다. 젊은 동료 교수들이 자신의 기술 블로그를 운영하는 것을 보며 나도 한번 해보자는 생각이 들었다. GitHub Pages와 Jekyll이라는 도구를 추천받았고, 특히 Chirpy 테마가 깔끔하다고 해서 바로 따라 해보기로 결심했다.

처음 며칠간은 정말 잘되는 것처럼 보였다. GitHub 리포지토리를 만들고, Jekyll을 로컬에 설치하고, Chirpy 테마를 적용했다. 로컬 환경에서 bundle exec jekyll serve를 실행하면 완벽하게 작동했다. 색상도 예쁘고, 내비게이션도 부드럽고, 글꼴도 세련되어 보였다. 몇 개의 포스트를 작성하고 GitHub에 푸시했을 때 나는 마치 자신의 첫 논문이 SCI 저널에 수록된 것처럼 기뻤다.

배포 후 CSS 파일이 로드되지 않는 악몽

그런데 문제는 배포 후 몇 시간 뒤에 발생했다. GitHub Pages에 접속해보니… 글씨는 나오지만 스타일이 없었다. 검은 글씨, 흰 배경, 어떤 꾸밈도 없는 상태였다. 마치 1990년대 초반 웹사이트를 보는 것 같은 느낌이었다. 로컬 환경에서는 완벽한데 배포 후에는 CSS가 적용되지 않는 현상이었다.

처음에는 캐시 문제인 줄 알았다. 브라우저 캐시를 지우고, 시크릿 모드로 접속해봤지만 변함없었다. GitHub Pages 서버의 문제인가 싶어서 몇 시간을 기다렸다가 다시 접속해봤지만 그대로였다. 그때의 답답함은 이루 말할 수 없었다. 로컬에서는 완벽하게 작동하는데 배포 후에는 작동하지 않는 현상 - 개발자들은 이것을 “로컬에서는 되는데?”라는 문제라고 부른다. 나는 3시간 동안 GitHub의 공식 문서를 뒤지고, 스택오버플로우를 읽고, 다양한 포럼을 방문했다.

원인 찾기 - 브라우저 개발자 도구의 중요성

문제를 찾은 것은 브라우저의 개발자 도구였다. F12를 눌러서 콘솔 탭을 확인해보니, 수십 개의 404 에러가 떠있었다. CSS 파일을 찾을 수 없다는 메시지였다. 그리고 더 자세히 보니 URL이 이상했다. 로컬에서는 /assets/css/style.css였지만, 배포된 페이지에서는 잘못된 경로를 가지고 있었다.

이 순간 깨달음이 왔다. 내가 설정한 리포지토리 이름이 username.github.io가 아니라 my-blog였던 것이다! GitHub Pages는 username.github.io 형식의 리포지토리에만 루트 도메인에 배포된다. 다른 이름의 리포지토리에 배포하면 username.github.io/my-blog 경로에 배포되는데, Jekyll이 이를 제대로 인식하지 못했던 것이었다.

해결책 - _config.yml의 baseurl 설정

해결책은 의외로 간단했다. 프로젝트 루트의 _config.yml 파일을 열어서 baseurl 설정을 수정하면 되었다. 나는 다음과 같이 수정했다:

baseurl: "/my-blog"

이 한 줄의 설정 변경이 모든 리소스 경로(CSS, JavaScript, 이미지 등)에 자동으로 /my-blog 접두사를 붙여주게 되었다. 변경 후 다시 로컬에서 테스트해봤을 때, bundle exec jekyll serve로 빌드된 사이트의 URL이 localhost:4000/my-blog였다. GitHub에 푸시한 후 페이지를 새로고침하니… 모든 스타일이 완벽하게 적용되었다!

이 경험이 나에게 준 깨달음

이 3시간의 삽질은 나에게 귀중한 경험을 선사했다. 첫째, 로컬 개발 환경과 프로덕션 환경의 차이를 제대로 이해하는 것의 중요성. 둘째, 문제 해결 시 브라우저의 개발자 도구가 얼마나 강력한 도구인지. 셋째, 설정 파일을 꼼꼼히 읽어야 한다는 것이다.

많은 초보 개발자들(그리고 늦게 개발을 배우는 교수들)이 같은 문제로 고민하고 있을 것이 분명하다. 특히 GitHub Pages의 특성상 리포지토리 이름에 따라 배포 경로가 달라진다는 것을 모르는 경우가 많다. baseurl 설정은 단순해 보이지만, 이것이 얼마나 중요한지는 배포 후에야 깨닫게 된다.

Jekyll Chirpy 테마 사용자