GitHub Pages에서 Jekyll 빌드 실패? 로컬 환경 구성이 답입니다

나는 왜 GitHub Pages에서 자꾸 실패했나

2015년 대학을 정년퇴직하고 나서 여가 시간을 활용해 기술 블로그를 시작하겠다고 마음먹었습니다. 당시 저는 60대 초반이었지만, 30년간의 컴퓨터 과학 교수 경험을 정리하고 싶었거든요. GitHub Pages와 Jekyll을 추천받았고, 큰 기대를 가지고 시작했습니다.

하지만 현실은 녹록지 않았습니다. 마크다운으로 글을 작성하고 GitHub에 푸시하면, 자동으로 블로그가 구축될 줄 알았는데, 계속 빌드 오류 메일이 날아왔습니다. “Build failed”라는 메일을 받을 때마다 한숨이 나왔습니다. 원인을 찾기 위해 GitHub의 Actions 탭을 뒤져봐도, 초보자로서는 어느 부분이 문제인지 파악하기 어려웠습니다.

그렇게 좌충우돌하다가 깨달은 것이 있습니다. 바로 로컬 환경에서 먼저 완벽하게 테스트한 후에 GitHub에 올려야 한다는 점입니다. 이제 제가 배운 경험을 여러분과 나누고 싶습니다.

Ruby와 Jekyll을 로컬에 설치하는 것부터 시작하세요

GitHub Pages의 빌드 시스템은 원격 서버에서 작동하기 때문에, 서버 환경과 정확히 같은 로컬 환경을 구성하는 것이 중요합니다. 저는 처음에 이 단계를 건너뛰고 싶었는데, 그것이 얼마나 큰 실수였는지 나중에 깨달았습니다.

먼저 Ruby를 설치해야 합니다. GitHub Pages는 Ruby 기반의 Jekyll을 사용하므로, Ruby 버전이 일치하지 않으면 로컬과 서버에서 다른 결과가 나올 수 있습니다. 저는 처음에 Ruby 2.7을 사용했다가, GitHub Pages 업데이트 이후 3.1로 변경해야 했습니다. 이때 Gemfile에서 ruby 버전을 명시적으로 지정하는 것이 얼마나 중요한지 체험했습니다.

그 다음 Bundler를 통해 프로젝트 의존성을 관리합니다. bundle install 명령어로 Gemfile에 명시된 모든 gem을 설치하면, 로컬과 GitHub Pages 서버가 동일한 라이브러리 버전을 사용하게 됩니다. 저는 처음에 gem을 전역으로 설치했다가, 프로젝트마다 의존성이 충돌하는 문제를 겪었습니다. Bundler의 bundle exec 명령어를 사용하면 이런 문제를 완전히 해결할 수 있습니다.

bundle exec jekyll serve 명령어로 미리 확인하세요

이것이 제 작업 흐름을 완전히 바꿔놓은 가장 중요한 발견이었습니다. 로컬에서 bundle exec jekyll serve 명령어를 실행하면, 실제 GitHub Pages 서버에서 빌드되는 것과 동일한 방식으로 블로그가 컴파일됩니다.

저는 매일 아침 이 명령어를 먼저 실행합니다. 그러면 로컬호스트 4000번 포트에서 블로그가 실시간으로 서빙되며, 마크다운 파일을 수정하면 자동으로 재빌드됩니다. 이것만으로도 제 삶이 변했습니다. 더 이상 GitHub에 올린 후 빌드 오류를 받으며 기다릴 필요가 없었기 때문입니다.

69세인 지금도 매일 아침 이 명령어를 실행합니다. 브라우저에서 localhost:4000으로 접속하면 내 블로그의 최종 결과물을 그대로 볼 수 있습니다. 날짜 형식이 제대로 표시되는지, 이미지 경로가 맞는지, 코드 하이라이트가 올바르게 작동하는지 모두 확인할 수 있습니다.

일반적인 빌드 오류들을 사전에 방지하세요

지난 10년간의 경험으로, 가장 흔한 빌드 오류들을 파악했습니다. 첫째는 YAML 형식의 Front Matter 오류입니다. 포스트의 맨 위에 있는 메타데이터 부분이 잘못되면 전체 빌드가 실패합니다. 특히 제목에 콜론이나 따옴표가 있을 때 주의해야 합니다.

둘째는 플러그인 호환성 문제입니다. GitHub Pages는 특정 플러그인만 허용합니다. 저는 처음에 마음대로 플러그인을 설치했다가, GitHub에서 빌드 오류를 받았습니다. GitHub Pages의 공식 문서에서 지원하는 플러그인 목록을 확인하고, 반드시 로컬에서 먼저 테스트해야 합니다.

셋째는 파일 경로와 인코딩 문제입니다. 특히 한글 파일명이나 특수문자가 있는 경로는 예상치 못한 오류를 일으킬 수 있습니다. 저는 모든 파일을 영문 이름으로 통일하고, UTF-8 인코딩을 명시적으로 사용합니다.

나의 일일 작업 프로세스

현재 제 작업 흐름은 다음과