GitHub Pages에서 Jekyll 빌드 실패? 로컬 테스트가 답이다

정말 답답했던 그 시절

30년을 대학에서 컴퓨터 공학을 가르친 후 은퇴한 나는, 여유 있는 노년을 보내기 위해 블로그를 시작하기로 결심했습니다. GitHub Pages와 Jekyll의 조합은 정말 훌륭했지만, 초반에는 정말 애를 먹었습니다. 코드를 수정해서 GitHub에 푸시하면 Build failed 메일이 날아오고, 무엇이 문제인지 알 수 없는 상황이 반복되었습니다.

그때는 마치 암흑 속에서 길을 잃은 것 같은 기분이었습니다. GitHub Actions 로그를 들여다봐도 어디서부터 뭐가 잘못되었는지 파악하기 어려웠거든요. 하지만 한 가지 깨달음이 있었으니, 바로 “로컬 환경에서 먼저 테스트해야 한다”는 것입니다. 이 경험을 공유하고자 합니다.

로컬 Jekyll 환경 구축하기

처음에는 복잡하게 생각했지만, 실제로는 매우 간단합니다. 제 경험상 Windows, macOS, Linux 모두에서 같은 방식으로 진행하면 됩니다.

먼저 Ruby를 설치해야 합니다. Ruby 3.0 이상을 권장하며, 공식 웹사이트에서 다운로드할 수 있습니다. 설치 후 터미널(또는 명령 프롬프트)을 열어 Ruby 버전을 확인하세요.

ruby --version

이제 Jekyll과 Bundler를 설치합니다. 이 단계는 정말 중요합니다. Bundler는 프로젝트의 gem 버전을 일관되게 관리해주는 도구인데, 저처럼 로컬과 GitHub Pages 환경의 불일치로 고생하지 않으려면 반드시 사용해야 합니다.

gem install jekyll bundler

블로그 디렉토리에 들어가서 다음 명령을 실행하세요.

bundle install

이 명령은 Gemfile을 읽어서 필요한 모든 패키지를 설치합니다. 처음 실행할 때 시간이 좀 걸릴 수 있습니다. 저도 처음엔 이 과정에서 에러가 많았는데, 대부분 gem 버전 호환성 문제였습니다.

빌드와 서버 실행하기

로컬 테스트의 핵심입니다. 다음 명령어 하나로 Jekyll 서버를 실행할 수 있습니다.

bundle exec jekyll serve

또는 더 자세한 정보를 보고 싶다면:

bundle exec jekyll serve --verbose

이제 브라우저에서 http://localhost:4000 에 접속하면 블로그를 볼 수 있습니다. 정말 신기했던 순간입니다. 마크다운 파일을 수정하고 저장하면 자동으로 재빌드되어 새로고침만으로 변경사항을 확인할 수 있거든요.

만약 포트 4000이 이미 사용 중이라면:

bundle exec jekyll serve --port 5000

이렇게 포트를 지정할 수 있습니다. 제 경우엔 다른 개발 작업과 충돌해서 자주 포트를 바꿨습니다.

흔한 빌드 오류와 해결법

지난 몇 년간 겪었던 오류들을 정리해봤습니다. 당신도 비슷한 문제로 고생한다면 참고하세요.

첫째, Gemfile.lock 불일치 문제입니다. GitHub와 로컬 환경의 gem 버전이 다르면 빌드가 실패합니다. 해결법은 간단합니다. bundle update 명령을 실행한 후 수정된 Gemfile.lock을 GitHub에 푸시하세요. 저는 이 방법으로 90% 이상의 빌드 오류를 해결했습니다.

둘째, 플러그인 호환성 문제입니다. GitHub Pages에서는 특정 플러그인만 지원합니다. 공식 문서에 listed plugins 목록이 있으니 반드시 확인하세요. 저는 처음에 지원하지 않는 플러그인을 설치해서 며칠을 헤맸습니다.

셋째, 프론트매터(Front Matter) 오류입니다. YAML 형식이 잘못되면 빌드가 실패합니다. 특히 콜론(:) 뒤에 공백이 없으면 안 됩니다. 로컬 테스트에서는 이런 오류가 명확하게 표시되므로, 빠르게 발견하고 수정할 수 있습니다.

결론

30년의 교육 경험을 통해 배운 것이 하나 있다면, “먼저 작은 규모에서 테스트하고 검증한 후 큰 무대에 나선다”는 것입니다. GitHub Pages도 마찬가지입니다. 로컬 환경에서 철저히 테스트하고 완벽하게 구동되는 것을 확인한 후 GitHub에 푸시하세요. 이렇게 하면 Build failed 메일로 답답해하지 않을 겁니다.

지금 바로 당신의 블로그 디렉토리에서 bundle exec jekyll serve 명령을 실행해보세요. 그리고 로컬에서 한 번 완벽하게 작동하는 경험을 해보시길 바랍니다.