Jekyll 블로그 배포 후 CSS가 안 먹히는 문제, 이렇게 해결했습니다

처음 마주친 난감한 상황

10년간 대학에서 컴퓨터공학을 가르쳤던 나는 은퇴 후 개인 기술 블로그를 운영하기로 결심했습니다. Jekyll과 GitHub Pages는 개발자들 사이에서 정평이 나 있다고 들어서 별 의심 없이 시작했는데, 첫 배포 후 상황은 예상 밖이었습니다.

로컬 환경에서는 완벽했습니다. Chirpy 테마를 적용한 후 bundle exec jekyll serve로 확인할 때 모든 스타일링이 정상적으로 작동했거든요. 하지만 GitHub에 푸시하고 Pages 배포를 활성화한 후 사이트에 접속하자마자 눈앞이 캄캄해졌습니다. 스타일이 완전히 벗겨진 흰색 배경의 텍스트만 남았거든요. 제 자식들에게 다시 물어봐야 한다는 생각이 들 정도였습니다.

이 문제는 제가 마주친 가장 흔하면서도 가장 답답한 Jekyll 배포 이슈였고, 다행히 해결책을 찾았습니다. 그 과정을 여러분과 나누고 싶습니다.

CSS 경로 문제의 정체

문제의 원인은 생각보다 간단했습니다. 바로 baseurl 설정이었습니다.

GitHub Pages에서 사용자 페이지(username.github.io)가 아닌 프로젝트 페이지를 운영할 경우, 모든 리소스는 https://username.github.io/repository-name/ 경로 아래에 위치하게 됩니다. 하지만 로컬 테스트 환경에서는 루트 경로(/)에서 바로 접근하므로 CSS 파일 경로가 달라집니다.

예를 들어, CSS 파일이 실제로는 /repository-name/assets/css/style.css에 위치하는데, baseurl을 설정하지 않으면 브라우저가 /assets/css/style.css를 찾으려고 시도하는 것입니다. 결과적으로 HTTP 404 에러가 발생하고 스타일시트 로드에 실패하는 거죠.

로컬 환경에서 문제가 드러나지 않는 이유는 Jekyll 개발 서버가 자동으로 경로를 처리하기 때문입니다. 하지만 실제 GitHub Pages 서버는 명시적인 설정 없이는 이를 알 수 없습니다.

실제 해결 방법 세 가지

첫 번째 방법: _config.yml에 baseurl 설정하기

가장 직접적이고 권장되는 방법입니다. 프로젝트의 루트 디렉토리에 있는 _config.yml 파일을 열어서 다음을 추가하면 됩니다:

baseurl: "/repository-name"

여기서 repository-name은 실제 GitHub 저장소 이름으로 바꿔야 합니다. 이것만으로도 대부분의 CSS 문제가 해결됩니다. Jekyll은 이 설정값을 모든 절대 경로 앞에 자동으로 붙여주기 때문입니다.

두 번째 방법: 로컬 테스트 시 baseurl 적용

baseurl을 설정하면 로컬 테스트할 때도 실제 배포 환경과 동일하게 테스트하고 싶을 수 있습니다. 이 경우 다음 명령어로 실행합니다:

bundle exec jekyll serve --baseurl ""

또는 baseurl을 포함해서:

bundle exec jekyll serve

개인 페이지를 운영한다면 _config.yml에서 baseurl을 비워두고, 필요할 때만 위 명령어로 로컬 테스트하는 것도 효과적입니다.

세 번째 방법: Chirpy 테마 특화 설정

Chirpy 테마를 사용한다면 추가로 확인해야 할 것들이 있습니다. _config.yml에서 url 항목도 함께 설정해야 합니다:

url: "https://username.github.io"
baseurl: "/repository-name"

Chirpy는 이 값들을 이용해 SEO와 소셜 미디어 공유 메타데이터를 생성하므로, 정확하게 설정하는 것이 중요합니다.

내가 깨달은 가장 큰 교훈

은퇴 후 기술 블로깅을 시작하면서 깨달은 것은, 로컬 환경과 실제 배포 환경이 다를 수 있다는 점이었습니다. 대학 강의실에서는 항상 “개발 환경과 배포 환경을 동일하게 구성하라”고 강조했지만, 이제야 그 조언의 무게를 실감합니다.

특히 Jekyll처럼 정적 사이트 생성기는 설정이 작지만 이 작은 설정이 크나큰 영향을 미칩니다. 처음 배포 후 3일간 원인을 찾지 못해 답답했던 기억이 남아있습니다. 그러나 한 번 문제를 해결하고 나니 비슷한 상황을 맞닥뜨린 후배 개발자들에게 도움을 줄 수 있게 되었습니다.

현재 저는 안정적으로 운영 중인 블로그에서 정기적으로 기술 글을 게재하고 있으며, 이제는 배포 후 스타일 검증도 자동화해두었습니다. 여러분도 이 경험을 통해 앞으로 비슷한 문제를 빠르게 해결할 수 있기를 바랍니다.

혹시 여러분의 Jekyll 블로그도 같은 문제를 겪고 있다면 지금 바로 _config.yml을 열어서 baseurl을 확인해보세요.