GitHub Pages에서 Jekyll 블로그가 갑자기 깨졌다? 빌드 실패의 원인과 해결책

지난주 월요일, 내가 운영하는 Jekyll 블로그가 갑자기 배포되지 않았다. 대학을 정년퇴직한 지 3년, 취미로 운영해온 기술 블로그였는데 말이다. GitHub Pages 대시보드를 확인하니 빨간 X 표시가 떠 있었다. ‘또 뭐가 문제지?’ 한숨이 나왔다. 30년 넘게 개발을 해온 내게도 이런 순간이 있다는 게 신기했다.

그날 밤새 문제를 추적하면서 깨달은 것이 있다. Jekyll 블로그의 빌드 실패는 예측 가능하고, 체계적으로 접근하면 충분히 해결할 수 있다는 것이다. 오늘은 내가 경험한 문제들과 해결책을 공유하려고 한다.

GitHub Pages 빌드 실패 메시지 읽는 법

처음부터 실수했다. 나는 GitHub Pages의 빌드 실패 알림 이메일을 무심코 지워버렸다. 퇴직 후 이메일이 많아서 대충 훑다가 말이다. 다시 확인하려고 GitHub 저장소 Settings 탭으로 들어갔다.

대부분의 개발자는 이 단계를 건너뛴다. 하지만 이게 핵심이다. GitHub Pages 설정 페이지 하단의 “GitHub Pages” 섹션에서 “Latest deployment” 상태를 꼭 확인해야 한다. 나는 거기서 처음으로 정확한 오류 메시지를 발견했다: “Liquid syntax error: Unknown tag ‘highlight’.”

이 메시지 하나로 내 문제의 30%는 해결됐다. Jekyll은 Liquid 템플릿 엔진을 사용하는데, 어딘가 문법 오류가 있다는 뜻이었다. 나는 최근에 포스트를 수정했던 기억이 났다. 코드 블록을 추가할 때 실수한 게 분명했다.

Gemfile과 플러그인 버전 충돌 문제

문제는 거기서 끝나지 않았다. 몇 가지 파일을 수정해도 여전히 빌드가 실패했다. 이번엔 다른 오류였다: “gem dependency error”.

은퇴 전에는 이런 문제를 팀의 주니어 개발자에게 물어봤을 텐데, 이제 나는 혼자다. 로컬 환경에서 bundle install을 실행해봤다. 결과는 예상대로였다. 내 Mac에 설치된 Ruby 버전과 Gemfile에 명시된 버전이 맞지 않았다.

여기서 배운 교훈: GitHub Pages는 특정 버전의 Jekyll과 플러그인만 지원한다. 공식 문서에 따르면 GitHub Pages가 지원하는 의존성 목록이 있다. 나는 처음엔 이걸 몰랐다. 내 로컬 Gemfile.lock을 GitHub의 버전에 맞춰야 했다.

해결책은 간단했다:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins

이렇게 수정하면, bundle install을 실행할 때 GitHub Pages가 공식 지원하는 정확한 버전들이 설치된다. 내가 원하던 플러그인이 없을 수도 있지만, 적어도 배포는 된다. 이건 타협이 아니라 안정성을 택하는 거다. 30년 경력을 가져도 이런 선택은 항상 맞다.

_config.yml 설정 오류와 인코딩 문제

세 번째 문제는 정말 예상 밖이었다. Chirpy 테마를 사용하다 보니 _config.yml 파일이 매우 복잡했다. 나는 몇 줄을 추가했는데, YAML 형식을 제대로 맞추지 않았다.

YAML은 들여쓰기에 매우 민감하다. Tab 키를 누르면 안 되고 스페이스만 써야 한다. 그리고 보통 2칸이다. 내가 실수한 부분은 리스트 아이템 앞의 대시 다음에 스페이스를 안 넣은 것이었다.

# 잘못된 예
categories:
-도구
-기술

# 올바른 예  
categories:
  - 도구
  - 기술

더 나아가서, 특수문자가 포함된 제목이나 설명을 쓸 때도 문제가 생길 수 있다. 큰 따옴표로 감싸거나 YAML 형식을 정확히 지켜야 한다. 내 블로그에는 한글이 많아서 더욱 주의해야 했다.

문제를 찾는 가장 좋은 방법은 온라인 YAML 검증 도구를 사용하는 것이다. 내가 자주 쓰는 사이트는 yamllint.com이다. _config.yml의 전체 내용을 복사해서 붙여넣으면 오류를 즉시 찾아준다.

로컬 테스트 환경 구축하기

이 모든 문제를 빠르게 해결하려면 로컬 환경에서 테스트하는 게 필수다. 나는 처음엔 무시했던 부분인데, 지금은 이게 얼마나 중요한지 안다.

bundle exec jekyll serve

이 명령어를 실행하면 로컬 서버(보통 http://localhost:4000)가 떠서 배포 전에 블로그를 미리 볼 수 있다. 만약 이 단