GitHub Pages에서 Jekyll 블로그가 갑자기 깨졌다? 빌드 오류 디버깅의 정석

세월이 흘러도 잊을 수 없는 그 날의 충격

저는 대학에서 30년간 컴퓨터공학을 가르친 교수입니다. 은퇴하고 나서 남은 인생을 의미 있게 보내고 싶어 개인 블로그를 시작했는데, 그것이 Jekyll이었습니다. 처음엔 모든 것이 잘 돌아갔습니다. GitHub 저장소를 만들고, Jekyll 테마를 적용하고, 포스트를 하나둘 올리며 즐거워하던 제 모습이 아직도 생생합니다.

그런데 어느 날 아침, 평상 같은 기분으로 블로그에 접속해보니 흰 화면만 떠있었습니다. 그것도 아무 에러 메시지 없이 말이죠. 당시 저는 혼란스러웠습니다. 교수 시절엔 수백 줄의 코드를 디버깅했던 경험이 있었지만, 이건 다른 문제였거든요. 그날부터 시작된 GitHub Pages 빌드 오류와의 전쟁을 통해 배운 경험들을 여러분과 나누고 싶습니다.

GitHub Pages 빌드 로그 읽기, 진짜 첫 번째 해결책

처음 문제가 생겼을 때 저는 터미널에서 jekyll serve 명령을 실행했습니다. 로컬에서는 잘 돌아갔어요. 이상했습니다. 로컬 환경과 GitHub Pages 서버 환경이 다르다는 걸 깨닫기까지 한참이 걸렸습니다.

GitHub Pages의 진정한 가치는 빌드 로그에 있습니다. 저장소의 Settings 탭에 들어가서 Pages 섹션을 보면, 최근 빌드 결과가 표시됩니다. 오류가 발생하면 빨간색으로 표시되죠. 저는 그 빌드 로그를 매우 소홀히 했습니다. 학교에선 항상 콘솔 창에 뜨는 에러를 읽었는데, GitHub Pages의 빌드 결과를 제대로 확인하지 않았던 거예요.

특별히 중요한 오류들은 다음과 같습니다:

Liquid 문법 오류: Jekyll은 Liquid 템플릿 언어를 사용합니다. 포스트 내에서 중괄호를 사용할 때 `` 처리를 제대로 하지 않으면 빌드가 실패합니다. 제 경우 마크다운 파일 안에서 Python 코드 예제를 보여주려다가 Liquid 변수로 인식되어 오류가 났었습니다.

플러그인 호환성 문제: GitHub Pages가 허용하는 플러그인은 매우 제한적입니다. 저는 처음엔 다양한 커뮤니티 플러그인을 사용하려다가 모두 제거해야 했습니다. _config.yml 파일에서 plugins: 섹션을 확인하고, 공식 허용 플러그인 목록만 사용해야 합니다.

프론트매터 YAML 오류: 포스트의 맨 위 메타데이터 부분에서 콜론이나 따옴표 처리가 잘못되면 전체 빌드가 실패합니다. 저는 포스트 제목에 특수문자를 사용했다가 YAML 파싱 오류로 고생했습니다.

로컬 테스트 환경 구축, 미리 잡는 오류의 가치

GitHub Pages에 올리기 전에 로컬에서 철저히 테스트하는 것이 얼마나 중요한지 깨달았습니다. 은퇴 후 처음엔 “아, 올려보면 되겠지”라는 마음이었지만, 여러 번의 실패를 거치니 생각이 바뀌었습니다.

저는 MacBook에 Ruby와 Bundler를 설치하고, 프로젝트 디렉토리에서 bundle install을 실행했습니다. 그 다음 bundle exec jekyll serve를 실행하면 http://127.0.0.1:4000에서 블로그를 미리 볼 수 있습니다. 이 과정에서 뜨는 모든 경고와 오류를 확인하고 수정하는 것이 중요합니다.

특히 유용했던 것은 --trace 옵션입니다. bundle exec jekyll serve --trace를 실행하면 매우 상세한 오류 메시지를 볼 수 있거든요. 제 경우 이것 덕분에 이미지 경로 오류를 찾을 수 있었습니다.

한 가지 더, GitHub의 Dependabot 알림도 무시하면 안 됩니다. Jekyll의 의존성 패키지들이 보안 업데이트되면 자동으로 알림이 옵니다. 처음엔 무시했다가 나중에 호환성 문제로 골치를 앓았습니다.

버전 호환성의 벽, 내가 마주친 가장 큰 적

은퇴하고 1년쯤 지났을 때, 무언가 이상했습니다. 예전에 잘 되던 포스트들이 갑자기 스타일이 깨지기 시작했거든요. 조사해보니 GitHub Pages가 Jekyll 버전을 업그레이드했고, 저의 Chirpy 테마도 업데이트가 필요했습니다.

이 문제를 해결하기 위해 저는 다음을 수행했습니다:

먼저 로컬 저장소에서 테마의 GitHub 저장소를 확인했습니다. Chirpy 테마의 경우 Gemfile을 살펴보면 모든 의존성 버전이 명시되어 있습니다. 저는 이를 통해 제 로컬 환경이 얼마나 뒤처져 있는지 파악했습니다.

그 다음 bundle update를 실행하여 모든 gem을 최신 버전으로 업데이트했습니다. 이 과정에서 호환되지 않는 패키지가 있으면 Bundler가 알려줍니다. 저의 경우 새로운 Jekyll 버전에서 일부 필터 함수의 동작이 바뀌어 있었고, 이를 반영하기 위해 _includes 디렉토리의 액체 파일들을 수정해야 했습니다.

특히 기억에 남는 것은 jekyll-paginate-v2라는 플러그인 때문에 고생한 일입니다. 이것은 GitHub Pages의 공식 허용 플러그인이 아니었는데, 제가 처음엔 이를 모르고 사용했거든요. 몇 달 동안 왜 pagination이 작동 안 하는지 몰랐다가 마침내 깨달았을 때는 정말 허탈했습니다.

내 경험이 당신의 방패가 되기를

지난 5년간 이 블로그를 운영하며 저는 매우 많은 것을 배웠습니다. 교수 시절에 배운 논리적 사고와 문제 해결 능력이 여기서도 매우 유용했습니다. 하지만 무엇보다 중요했던 것은 작은 변화를 꾸준히 테스트하는 습관이었습니다.

새 포스트를 올릴 때마다 로컬에서 완벽하게 테스트하고, GitHub에 푸시하기 전에 빌드 로그를 확인합니다. 이런 간단한 루틴이 얼마나 많은 시간과 스트레스를 절약해주는지 모릅니다.

Jekyll과 GitHub Pages는 정말 훌륭한 도구입니다. 초기 세팅만 제대로 하고 몇 가지 원칙만 지킨다면, 누구나 안정적인 블로그를 유지할 수 있습니다. 저처럼 은퇴 후 새로운 취미로 블로그를 시작하는 분들도 있을 테고, 개발자로 자신의 지식을 공유하려는 분들도 있을 것입니다.

혹시 당신도 GitHub Pages 블로그를 운영 중이라면, 오늘 한번 빌드 로그를 확인해보세요. 혹은 로컬 환경에서 bundle exec jekyll serve --trace를 실행해서 숨어있는 경고들을 찾아내보세요. 작은 문제 하나를 해결할 때마다 당신의 블로그는 더 견고해질 것입니다.

당신의 GitHub Pages 블로그에서 마주친 오류와 그 해결책을 아래 댓글로 공유해주세요. 함께 배우고 성장하는 것이 지식의 참된 의미라고 생각합니다.