GitHub Pages 빌드 실패의 90%를 해결하는 Jekyll 설정 비법
30년 개발자 경험으로 전하는 GitHub Pages Jekyll 빌드 오류 해결법
지난 15년간 대학에서 웹 개발을 가르치면서 가장 많이 받은 질문이 바로 “GitHub Pages에서 Jekyll 블로그가 왜 안 될까요?”라는 것입니다. 교수로 은퇴한 지금도 후배 개발자들에게 이 문제 때문에 연락을 받곤 합니다. 오늘은 제가 2000명 이상의 학생과 개발자를 돕으면서 발견한 실전 노하우를 공유하겠습니다.
GitHub Pages 환경과 로컬 환경의 미묘한 차이
가장 흔한 실수부터 이야기하겠습니다. 저도 처음엔 “로컬에선 잘 되는데 GitHub에 푸시하면 안 돼”라며 답답해했습니다. 그 이유는 두 환경이 완전히 다르기 때문입니다.
로컬 컴퓨터에서는 최신 버전의 Ruby와 Jekyll, 각종 플러그인을 자유롭게 설치할 수 있습니다. 그러나 GitHub Pages는 특정 버전의 Jekyll(현재 3.9)만 지원하며, 허용된 플러그인도 제한됩니다. 이 차이를 모르고 _config.yml에 GitHub에서 지원하지 않는 플러그인을 추가하면 빌드가 실패하는 것입니다.
제 해결책은 간단합니다. Gemfile에 github-pages gem을 명시적으로 추가하는 것입니다. 이렇게 하면 로컬 환경이 GitHub Pages와 동일한 환경을 구성하게 됩니다.
1
gem "github-pages", "~> 231", group: :jekyll_plugins
그 후 bundle install을 실행하면, 로컬에서 발생하는 오류를 미리 감지할 수 있습니다. 이것이 제가 수백 명의 학생들을 도울 때 가장 효과적이었던 첫 단계입니다.
_config.yml의 숨겨진 함정들
_config.yml 파일은 Jekyll의 심장입니다. 하지만 이 파일의 문법 오류나 설정 충돌 때문에 빌드가 실패하는 경우가 정말 많습니다.
특히 주의해야 할 점은 들여쓰기(indentation)입니다. YAML 형식은 공백에 매우 민감합니다. 탭 문자와 스페이스를 혼용하면 안 되며, 반드시 스페이스 2칸 또는 4칸으로 통일해야 합니다. 저는 학생들을 지도할 때 항상 스페이스 2칸을 권장했습니다.
또한 GitHub Pages에서 지원하지 않는 플러그인들이 있습니다. jekyll-admin, jekyll-require-login 같은 것들이 대표적입니다. 이러한 플러그인들은 로컬에서는 작동하지만 GitHub 서버에서는 보안상의 이유로 비활성화됩니다. GitHub 공식 문서에서 제공하는 허용 플러그인 목록을 반드시 확인하세요.
1
2
3
4
plugins:
- jekyll-feed
- jekyll-sitemap
- jekyll-seo-tag
이 세 가지는 GitHub Pages에서 공식 지원하는 플러그인이므로 안전하게 사용할 수 있습니다.
빌드 로그 읽는 법과 디버깅 전략
GitHub에서 빌드가 실패하면 저장소 Settings의 “Pages” 섹션에서 오류 메시지를 확인할 수 있습니다. 많은 개발자들이 이 메시지를 무시하는데, 이것이 바로 금맥입니다.
제 경험상 가장 자주 나타나는 오류 메시지는 “Liquid Exception”입니다. 이는 Jekyll 템플릿 엔진이 문법을 이해하지 못했다는 뜻입니다. 특히 포스트 파일에서 {{ }}나 {% %} 문법을 사용할 때 이런 일이 발생합니다.
더 깊이 있는 디버깅을 원한다면 GitHub Actions를 활용하세요. 저장소에 .github/workflows/jekyll.yml 파일을 추가하면 모든 빌드 과정을 로그로 볼 수 있습니다:
1
2
3
4
5
6
7
8
9
10
11
12
name: Build and deploy Jekyll site
on: [push]
jobs:
jekyll:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: ruby/setup-ruby@v1
with:
ruby-version: 3.1
bundler-cache: true
- run: bundle exec jekyll build
이 워크플로우를 사용하면 push할 때마다 자동으로 빌드를 시도하고 상세한 로그를 남깁니다. 저는 이 방법으로 지난 5년간 한 번도 GitHub Pages 빌드 문제로 고민하지 않았습니다.
교수 생활 중 가장 보람 있었던 순간 중 하나는 이런 팁들로 학생들이 막혔던 문제를 해결하는 것을 보는 것이었습니다. 여러분도 이 세 가지 원칙—환경 통일, 설정 검증, 로그 분석—을 기억하신다면 GitHub Pages 빌드 오류는 더 이상 악몽이 되지 않을 것입니다. 지금 바로 여러분의 저장소를 점검해보세요.