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

처음 깨달은 충격적인 진실

정년을 앞두고 취미로 블로그를 시작하려던 2024년 봄, 저는 GitHub Pages와 Jekyll이라는 이름만 들었을 뿐 제대로 알지 못했습니다. “무료로 블로그를 운영할 수 있다던데”라는 가벼운 마음으로 시작한 것이 큰 실수였죠.

처음 며칠간 저는 GitHub에 테마를 다운로드해서 리포지토리에 올리면 자동으로 완벽한 블로그가 만들어질 거라고 순진하게 생각했습니다. 하지만 현실은 냉혹했습니다. 빨간 X 표시와 함께 나타난 “Build failed” 메시지 앞에서 저는 무너져 내렸습니다. 이제 와서 생각해보니, 로컬 환경에서 먼저 테스트하지 않고 바로 푸시한 것이 문제였습니다.

그 이후 3개월간 저는 Ruby, Bundler, Jekyll의 세계로 빠져들었습니다. 그리고 이제 저는 확신을 가지고 말할 수 있습니다. 로컬 개발 환경을 제대로 설정하는 것이 모든 문제를 해결한다는 것을 말입니다.

Ruby 환경 설정: 기초 공사를 제대로 하자

Jekyll은 Ruby라는 프로그래밍 언어 위에 구축된 정적 사이트 생성기입니다. 마치 집을 지을 때 기초 공사가 중요한 것처럼, Ruby의 올바른 버전을 설치하는 것은 필수입니다.

저는 처음에 시스템 Ruby를 그대로 사용했다가 Bundler 충돌로 인해 며칠을 낭비했습니다. 이제는 rbenv나 RVM 같은 Ruby 버전 관리자를 강력히 추천합니다. macOS 사용자라면 Homebrew로 rbenv를 설치하고, Windows 사용자라면 RubyInstaller를 사용하세요. 정년을 맞이하면서 “이제 천천히 배울 시간이 있다”고 생각했던 저도 이 부분에서 빠른 결정이 중요함을 깨달았습니다.

GitHub Pages는 현재 Ruby 3.1 버전을 지원하므로, 로컬에서도 같은 버전을 사용하는 것이 가장 안전합니다. 버전 호환성 문제는 예상치 못한 순간에 나타나곤 합니다.

Gemfile과 Bundler: 의존성 관리의 정석

저의 두 번째 큰 깨달음은 Gemfile과 Bundler의 중요성이었습니다. GitHub Pages에서 빌드 실패하는 대부분의 이유는 로컬 개발 환경과 서버 환경의 gem 버전이 맞지 않기 때문입니다.

올바른 Gemfile 설정은 마치 요리 레시피를 정확히 적는 것과 같습니다. Chirpy 테마를 기준으로 설명하자면, bundle install을 실행할 때 Gemfile.lock 파일이 생성됩니다. 이 파일을 반드시 GitHub에 커밋해야 합니다. 저는 처음 .gitignore에 의해 이 파일이 제외되어 있다는 사실을 모르고 며칠간 헤맸던 경험이 있습니다.

GitHub Pages에서 빌드할 때 로컬의 Gemfile.lock 파일을 기준으로 정확히 같은 버전의 gem을 설치하게 됩니다. 따라서 로컬에서는 bundle exec jekyll serve를 사용하여 Bundler가 관리하는 gem 환경에서 Jekyll을 실행해야 합니다. 이것만으로도 90%의 빌드 실패 문제가 해결될 것입니다.

로컬 테스트: 완벽한 검증의 힘

정년 후 블로깅의 가장 좋은 점은 시간이 충분하다는 것입니다. 저는 이제 새로운 포스트를 작성할 때마다 로컬에서 먼저 완벽하게 테스트합니다.

bundle exec jekyll serve 명령을 실행하면 로컬 서버가 http://localhost:4000에서 시작됩니다. 이 단계에서 포스트가 제대로 렌더링되는지, 스타일이 적용되는지, 링크가 올바른지 모두 확인할 수 있습니다. 나이 많은 사람이 가진 장점은 실수를 거듭할수록 더욱 신중해진다는 것이거든요.

특히 YAML 프론트매터의 문법 오류는 반드시 로컬에서 먼저 발견해야 합니다. 따옴표 문제, 들여쓰기 오류, 날짜 형식 불일치 같은 것들은 GitHub에서 빌드 로그를 확인하기 전에 로컬에서 먼저 해결하는 것이 시간을 많이 절약합니다.

빌드 성공의 순간까지

제가 처음으로 “Build successful”이라는 초록색 체크 표시를 본 그날, 저는 웃음이 나왔습니다. 기술이 완전히 다른 분야였던 은퇴 교수의 입장에서 보면, 이것은 대학원 학생이 논문을 처음 게재했을 때의 기쁨과 비슷했습니다.

이제 여러분도 이러한 설정을 따라 하신다면 GitHub Pages에서 더 이상 빌드 실패를 경험하지 않을 것입니다. 로컬 환경을 제대로 설정하는 것만으로도 99%의 문제가 해결되며, 나머지 1%는 공식 문서와 커뮤니티의 도움으로 충분히 해결할 수 있습니다.

지금 바로 본인의 Jekyll 프로젝트 폴더에서 bundle install을 실행하고, bundle exec jekyll serve로 로컬 서버를 띄워서 완벽한 블로그 환경을 구축해보세요. 그리고 첫 번째로 성공한 빌드의 기쁨을 경험해 보시길 바랍니다.