GitHub Pages 배포 실패의 악몽에서 깨어나다: Jekyll 빌드 에러 완벽 해결법

은퇴 후 블로그를 시작하며 마주친 첫 번째 벽

정년퇴직 후 제 경험을 나누기 위해 블로그를 시작하기로 결심했습니다. 아들이 추천한 Jekyll과 GitHub Pages를 이용해 무료로 블로그를 만들 수 있다고 했거든요. 처음에는 간단할 줄 알았습니다. GitHub에 저장소를 만들고, Jekyll 테마를 선택한 후 글을 쓰면 끝이라고 생각했죠.

하지만 현실은 달랐습니다. 첫 번째 포스트를 작성하고 GitHub에 푸시했을 때, GitHub Pages는 침묵으로 응했습니다. 배포가 되지 않은 것입니다. 이메일을 확인해보니 “Build failed”라는 차가운 메시지가 있었습니다. 당시 저는 에러 메시지를 읽을 수조차 없었습니다. Gemfile, _config.yml, liquid syntax error 같은 단어들이 무엇인지 전혀 알 수 없었거든요.

GitHub Pages 빌드 에러를 이해하기

가장 먼저 해야 할 일은 에러 메시지를 정확히 읽는 것입니다. GitHub 저장소의 Settings 탭에서 Pages 섹션으로 들어가면, 빌드 실패 이유를 상세하게 볼 수 있습니다. 저는 여기서 발견한 가장 흔한 세 가지 문제를 정리했습니다.

첫째는 _config.yml 파일의 YAML 문법 오류입니다. 이 파일은 Jekyll의 설정을 담당하는데, 들여쓰기가 한 칸만 잘못되어도 전체 빌드가 실패합니다. 저는 처음에 카테고리 목록을 추가하다가 스페이스와 탭을 섞어 썼습니다. 인간의 눈에는 같아 보이지만, 컴퓨터는 엄격합니다.

둘째는 gem 버전 충돌입니다. Chirpy 테마를 설치했을 때, Gemfile에 명시된 gem들의 버전이 로컬 환경과 GitHub의 서버 환경에서 다를 수 있습니다. 특히 jekyll-theme-chirpy 버전과 jekyll 버전 사이의 호환성이 중요합니다.

셋째는 포스트 파일명의 형식 오류입니다. Jekyll은 yyyy-mm-dd-title-format을 요구합니다. 저는 처음에 날짜 형식을 잘못 입력해서 포스트가 발행되지 않은 적이 여러 번 있었습니다.

로컬 환경에서 먼저 테스트하는 지혜

이 모든 문제를 겪으면서 배운 가장 중요한 교훈은 GitHub에 푸시하기 전에 로컬에서 먼저 테스트하는 것입니다. 현재 저는 포스트를 작성한 후 반드시 bundle exec jekyll serve 명령어를 실행합니다. 이 명령어는 로컬 서버를 시작해서 http://localhost:4000 에서 블로그를 미리 볼 수 있게 합니다.

로컬 테스트는 마치 비행기 조종사의 시뮬레이터처럼 작동합니다. 실제 환경과 거의 동일한 조건에서 테스트하고, 문제가 있으면 즉시 수정할 수 있습니다. 저는 이 방법으로 99%의 빌드 에러를 배포 전에 잡아낼 수 있게 되었습니다.

더불어 bundle update를 주기적으로 실행하여 gem들을 최신 버전으로 유지하는 것도 중요합니다. 낡은 의존성은 새로운 호환성 문제를 야기합니다. 저는 한 달에 한 번씩 이 작업을 수행하는 습관을 들였습니다.

실제로 도움이 된 디버깅 팁들

몇 년간의 블로깅 경험을 통해 축적한 디버깅 팁들이 있습니다. 첫째, _config.yml을 수정했을 때는 반드시 로컬 서버를 재시작해야 합니다. 파일을 저장했다고 해서 자동으로 반영되지 않습니다.

둘째, Liquid 템플릿 문법에 주의해야 합니다. 포스트 본문에서 이중 중괄호를 사용할 때 Jekyll이 이를 변수로 인식할 수 있습니다. 코드를 예시로 든다면 raw 태그로 감싸야 합니다.

셋째, GitHub의 Actions 탭을 확인하면 빌드 과정의 상세 로그를 볼 수 있습니다. 이것이 가장 정확한 에러 정보를 제공합니다. 저는 이제 빌드 실패 시 이곳을 가장 먼저 방문합니다.

마지막으로 강조하고 싶은 것은 인내심입니다. 은퇴 후 새로운 기술을 배우는 것은 쉽지 않았습니다. 하지만 한 번 익혀두면, Jekyll과 GitHub Pages는 여러분의 디지털 자산이 되어줍니다. 유지비 없이 영구적으로 운영할 수 있기 때문입니다.

지금 여러분이 비슷한 빌드 에러로 고민하고 있다면, 절대 혼자가 아닙니다. 저도 그런 시간을 거쳤고, 지금은 매주 새로운 글을 문제없이 발행하고 있습니다. 이 글의 방법들을 따라 시도해보시고, 혹시 막히는 부분이 있다면 GitHub 커뮤니티나 Stack Overflow에 질문을 올려보세요. 누군가는 반드시 도와줄 것입니다.

여러분의 첫 번째 성공적인 Jekyll 배포를 응원합니다. 지금 바로 로컬 환경을 설정하고 테스트해보세요.