GitHub Pages 배포 실패? Jekyll 빌드 에러 10가지 한 번에 해결하기

서른 해를 전산학과 교수로 일하다 퇴직한 지 어언 3년

나는 은퇴 후 취미로 Jekyll 블로그를 시작했습니다. 학창 시절 배웠던 HTML, CSS는 한낱 추억이었지만, GitHub Pages라는 무료 플랫폼이 있다는 걸 알고 도전했죠. 하지만 시작은 녹록지 않았습니다. 첫 배포 때부터 빌드 에러의 늪에 빠졌거든요. 지난 3년간 직접 겪으며 해결했던 경험들을 후배 개발자들과 나누고 싶어서 이 글을 씁니다.

Jekyll 빌드가 자꾸 실패하는 이유들

1. Gemfile 의존성 충돌 문제

가장 먼저 만난 적은 Gemfile이었습니다. GitHub Pages가 지원하는 jekyll 버전과 내 로컬 환경의 버전이 맞지 않으면 빌드에 실패합니다. 특히 bundle exec jekyll serve 명령어를 쓸 때 주의가 필요했어요.

해결 방법은 간단합니다. Gemfile에 명시적으로 GitHub Pages가 지원하는 버전을 지정하는 것입니다:

gem "github-pages", group: :jekyll_plugins

그리고 bundle update를 실행하면 됩니다. 이 과정에서 로컬과 서버의 환경이 동기화되어 많은 문제가 자동으로 해결됩니다.

2. _config.yml 문법 오류

두 번째 관문은 YAML 문법이었습니다. 공백 하나가 틀려도 빌드가 깨집니다. 특히 한글 제목을 사용할 때 인코딩 문제도 발생했어요. 초반에 이걸 모르고 며칠을 헤맸습니다.

제일 간단한 해결책은 _config.yml 파일을 온라인 YAML 검증 도구로 확인하는 것입니다. 또한 파일 맨 앞에 encoding: utf-8을 명시하면 한글 처리가 훨씬 수월합니다. 저는 지금도 수정할 때마다 한 번씩 검증합니다.

3. 레이아웃 파일 경로 오류

포스트의 front matter에서 레이아웃을 지정할 때 실수하기 쉽습니다. layout: post라고 썼는데 실제 파일명이 _layouts/posts.html이면 당연히 안 되죠. 저는 초기에 이런 식으로 여러 번 실패했습니다.

해결 방법은 _layouts 폴더에 있는 파일들을 정확히 확인하고, 정확한 파일명(확장자 제외)을 지정하는 것입니다. Jekyll 공식 문서의 기본 템플릿을 그대로 따르는 것도 좋은 방법입니다.

실전 팁: GitHub 액션 로그 읽기

GitHub Actions 탭에서 자세한 에러 메시지를 볼 수 있다는 걸 몇 주 뒤에 알았습니다. 그 전까지는 “Build failed”라는 짧은 메시지만 보고 답답했거든요. 이제 배포 실패하면 먼저 Actions 탭으로 달려갑니다.

로그를 읽는 팁은 이렇습니다:

• Liquid Exception으로 검색하면 테마 관련 에러를 빠르게 찾을 수 있습니다
• 줄 번호를 확인해서 어느 파일의 몇 번 줄인지 파악합니다
• 에러 메시지의 맨 아래 부분이 실제 원인인 경우가 많습니다

나머지 5가지 에러와 해결책

4번 플러그인 비활성화 문제는 _config.yml의 plugins 섹션을 확인하고, GitHub Pages가 공식 지원하는 플러그인만 사용해야 합니다. 5번 포스트 파일명 형식은 반드시 YYYY-MM-DD-제목.md 형식을 지키고, 6번 마크다운 렌더링은 kramdown을 기본값으로 두면 대부분 해결됩니다.

7번 이미지 경로 오류는 /assets/ 절대 경로를 사용하고, 8번 특수 문자 처리는 YAML에서 따옴표로 감싸면 됩니다. 9번 캐시 문제는 로컬에서 bundle exec jekyll clean을 자주 실행하고, 10번 로컬과 서버 환경 차이는 bundle lock 파일을 깃허브에 커밋함으로써 해결할 수 있습니다.

마치며

은퇴 후 처음으로 실제 문제를 해결하며 배우는 즐거움을 느꼈습니다. 이 글이 누군가의 답답함을 덜어주고, GitHub Pages 블로그를 성공적으로 운영하는 데 도움이 되기를 바랍니다. 혹시 본인이 겪은 빌드 에러가 있다면, 오늘 소개한 10가지 해결책을 차례대로 체크해보세요.