GitHub Pages 배포 실패? Jekyll 빌드 에러 디버깅 완벽 가이드

은퇴 후 시작한 개발 블로그의 좌충우돌

40년간 정보통신 교수로 일한 후 은퇴한 지 이제 2년째입니다. 마침내 시간이 생겼다고 생각해 개인 블로그를 시작하기로 마음먹었을 때, 가장 먼저 선택한 것은 Jekyll과 GitHub Pages였습니다. “무료이고, 깃허브와 연동되고, 마크다운으로 글을 쓸 수 있다”는 장점이 너무 매력적이었거든요.

그런데 첫 배포 시도는 참담했습니다. 로컬에서 jekyll serve로 완벽하게 보이던 블로그가 GitHub에 푸시한 순간, 오류 메일이 날아왔습니다. “Your site failed to build.” 그 메일을 받을 당시의 좌절감은 아직도 생생합니다. 이후 6개월간 이러한 빌드 에러와 씨름하며 터득한 경험을 여러분과 나누고 싶습니다.

가장 흔한 5가지 빌드 에러와 해결책

1. Gemfile 버전 충돌 문제

제 첫 번째 문제는 로컬 개발 환경과 GitHub Pages 서버의 Ruby 버전 차이였습니다. 제 컴퓨터에는 Ruby 3.2가 설치되어 있었는데, GitHub Pages는 더 낮은 버전의 Ruby를 사용하고 있었습니다. 그 결과 로컬에서 문제없던 젬(gem)들이 서버에서 호환되지 않았던 것입니다.

해결책은 간단했지만, 우리 세대에는 직관적이지 않았습니다. Gemfile에 github-pages 젬을 명시적으로 추가하고, 버전을 고정하는 것입니다. 저는 다음과 같이 설정했습니다:

gem "github-pages", "~> 230", group: :jekyll_plugins

이렇게 하면 GitHub Pages와 동일한 환경을 로컬에서 시뮬레이션할 수 있습니다. bundle update를 실행하면 Gemfile.lock 파일이 생성되는데, 이것을 꼭 깃허브에 커밋해야 한다는 점을 기억하세요.

2. 플러그인 호환성 문제

은퇴하고 유튜브로 개발 튜토리얼을 봤는데, 어느 채널에서는 멋진 플러그인을 소개했습니다. SEO 최적화, 사이트맵 자동 생성, 압축 기능들이었죠. 저는 욕심내서 한 번에 다섯 개의 플러그인을 추가했습니다. 그리고 배포했을 때 또다시 빌드 실패가 났습니다.

GitHub Pages는 보안상의 이유로 모든 플러그인을 지원하지 않습니다. 공식 문서에 명시된 플러그인들만 사용할 수 있습니다. 저는 공식 지원 플러그인 목록을 확인한 후, 다음과 같이 _config.yml을 설정했습니다:

plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-sitemap

지원되지 않는 플러그인은 별도로 빌드해야 한다면, GitHub Actions를 사용해 커스텀 빌드 파이프라인을 구성하는 방법도 있습니다.

3. 파일명과 인코딩 문제

세 번째 문제는 정말 당황스러웠습니다. 파일명이 한글이거나 공백을 포함할 경우, Windows와 macOS, Linux 간에 파일명을 인식하는 방식이 달라서 빌드 에러가 발생했습니다. 또한 텍스트 파일의 인코딩이 UTF-8이 아니면 Jekyll이 파일을 제대로 파싱하지 못했습니다.

저는 철저하게 다음 규칙을 정했습니다:

• 모든 이미지와 포스트 파일명은 영문 소문자와 하이픈만 사용
• 모든 텍스트 파일은 UTF-8 인코딩 (BOM 없음)
• 파일명에 공백 절대 금지

이런 규칙을 정한 후 약 한 달간 기존 파일들을 정리했는데, 이후로는 빌드 에러가 거의 사라졌습니다.

로컬 빌드 환경 설정과 디버깅 기법

로컬에서 GitHub Pages와 동일한 환경을 만드는 것이 가장 중요합니다. 저는 다음과 같은 명령어를 자주 사용합니다:

bundle exec jekyll serve --incremental --trace

--trace 옵션을 사용하면 에러 메시지가 매우 상세하게 출력됩니다. 이것이 저의 가장 큰 무기였습니다. 에러 스택 트레이스를 읽고 분석하는 능력이 생겼을 때, 비로소 대부분의 문제를 스스로 해결할 수 있게 되었습니다.

또한 GitHub 저장소의 “Settings” → “Pages” 섹션에서 빌드 로그를 확인할 수 있습니다. 배포 직후 여기서 상세한 에러 메시지를 볼 수 있으니, 매번 실패할 때마다 확인하는 습관을 들이시길 추천합니다.

마지막 조언: 점진적 접근의 중요성

제 경험에서 얻은 가장 중요한 교훈은 “한 번에 여러 변경을 하지 말 것”입니다. 한 두 가지만 수정하고 배포한 후, 성공을 확인한 다음 다음 변경사항을 진행하세요. 이렇게 하면 문제가 발생했을 때 원인을 훨씬 쉽게 파악할 수 있습니다.

지금 저는 매주 3~4개의 포스트를 꾸준히 올리고 있으며, 빌드 에러는 거의 발생하지 않습니다. 여러분도 이 가이드를 참고하여 GitHub Pages와 Jekyll로 안정적인 블로그를 구축할 수 있을 것입니다. 처음에는 답답할 수 있지만, 이 문제들을 하나씩 해결하면서 개발자로서 성장할 수 있다는 것이 제 경험입니다. 오늘 바로 여러분의 로컬 환경을 점검하고 --trace 옵션으로 빌드를 실행해 보세요.