GitHub Pages 배포 실패? Jekyll 로컬 빌드로 99% 문제를 해결하는 법

대학에서 전산학을 가르치다가 은퇴한 지 이제 5년쯤 되었습니다. 퇴직 후 그간의 교육 경험을 블로그로 정리하려고 Jekyll과 GitHub Pages를 시작했는데, 처음 한 달간은 정말 고생했던 기억이 납니다. 배포는 성공했다고 뜨는데 블로그가 깨져 보이고, 특정 포스트는 사이트맵에 안 나타나고, CSS가 먹통이 되기도 했거든요. 지금 되돌아보니 모두 로컬 환경에서 미리 테스트했으면 막을 수 있었던 문제들입니다.

Jekyll 로컬 빌드의 중요성: 원격 배포 전 최후의 보루

GitHub Pages에 푸시하기 전에 자신의 컴퓨터에서 정확히 어떻게 보일지 미리 확인하는 과정이 얼마나 중요한지는 몸으로 느껴봐야 알 수 있습니다. GitHub Pages의 빌드 시스템과 로컬 환경이 100% 동일하지 않을 수 있기 때문입니다. 제 경우 Chirpy 테마를 적용한 후 로컬에서는 완벽하게 보이는 포스트가 배포되면 이미지가 안 나타나는 현상이 발생했습니다. 한참을 헤매다가 결국 URL 경로 설정의 차이 때문이었음을 알게 되었습니다.

특히 강의 자료를 정리하던 당시에는 수식, 코드 블록, 테이블 등 복잡한 마크다운 요소들이 많았는데, 로컬 빌드 없이 직접 푸시했다가는 그야말로 재앙이었을 것 같습니다. 로컬 환경에서 먼저 테스트한다는 것은 단순히 시간을 아끼는 것을 넘어, 블로그의 신뢰성과 전문성을 지키는 필수 과정이라고 확신합니다.

Ruby 환경 설정부터 시작하기: 처음엔 난관이 가득하다

처음 Jekyll을 설치하려고 했을 때 가장 힘들었던 부분이 바로 Ruby 환경 구성입니다. 저는 처음엔 아무 생각 없이 Ruby를 설치했다가, Gem 의존성 문제로 한 시간을 낭비했습니다. 지금이라면 다음 순서대로 진행할 것 같습니다.

먼저 Ruby 3.1 이상을 설치하되, 각 운영체제별로 조금씩 다릅니다. Windows 사용자라면 RubyInstaller를 통해 설치하고, Mac 사용자라면 Homebrew로 brew install ruby를 실행하면 됩니다. Linux 사용자는 패키지 매니저를 통해 설치하되, 버전 관리를 위해 rbenv나 asdf 같은 도구를 함께 사용하는 것을 추천합니다. 저는 이 과정에서 여러 버전의 Ruby가 꼬이는 바람에 which ruby로 경로를 확인하고 수동으로 정리해야 했던 쓸쓸한 경험이 있습니다.

Ruby가 설치되면 gem install bundler jekyll로 Jekyll을 설치합니다. 그 다음 프로젝트 폴더에 들어가서 bundle install을 실행하면 Gemfile에 정의된 모든 의존성이 설치됩니다. Chirpy 테마를 사용한다면 별도의 Gemfile이 이미 있으므로, 그냥 이 명령어 하나로 모든 게 준비됩니다. 이 부분을 처음엔 제대로 이해하지 못해서 매번 의존성 충돌 에러를 만났었는데, 지금은 이게 얼마나 우아한 방식인지 알게 됩니다.

로컬 서버 실행과 실시간 수정: 개발의 진정한 재미

모든 환경 설정이 끝났다면 bundle exec jekyll serve 또는 간단히 jekyll serve 명령어로 로컬 서버를 띄울 수 있습니다. 이 명령어는 기본적으로 http://localhost:4000에서 블로그를 실시간으로 볼 수 있게 해줍니다. 저는 이 순간을 처음 경험했을 때 정말 감동했던 기억이 납니다. 마치 자신이 만드는 블로그를 실시간으로 보는 느낌이었거든요.

더욱 훌륭한 점은 --livereload 옵션을 추가하면 파일을 수정한 즉시 브라우저가 자동으로 새로고침 된다는 것입니다. bundle exec jekyll serve --livereload 명령어를 실행하면, 마크다운 파일이나 CSS, 레이아웃 파일을 수정했을 때 저장하는 순간 화면에 반영됩니다. 강의 자료를 정리하던 당시 이 기능이 없었다면 얼마나 비효율적이었을까 상상하니 끔찍합니다.

로컬 서버에서는 수식, 코드 블록, 이미지 경로, 카테고리 분류, 태그 클라우드 같은 모든 요소가 실제 배포된 모습과 동일하게 표시됩니다. 특히 responsive 디자인이 제대로 작동하는지 확인하려면 브라우저의 개발자 도구에서 모바일 뷰로 전환해볼 수 있습니다. 저는 이 방식으로 태블릿과 스마트폰에서 어떻게 보일지 미리 점검하고 배포했기에, GitHub Pages 배포 후 별다른 문제가 없었던 것 같습니다.

빌드 에러 로그 분석: 에러 메시지는 친구다

로컬 빌드 중 에러가 발생하면 터미널에 상세한 로그가 출력됩니다. 처음엔 이 로그가 여간 복잡해 보이지 않습니다. 하지만 차분히 읽다 보면 어느 파일의 몇 번째 줄에서 문제가 생겼는지 명확하게 드러나 있습니다. 예를 들어 마크다운 파일의 Front Matter 형식이 잘못되었다면 “Liquid Exception”이라는 에러가 뜨고, 플러그인이 호환되지 않으면 “Plugin not found” 에러가 나타납니다.

저는 초반에 YAML 들여쓰기를 탭으로 했다가 에러를 만났고, 플러그인 버전 충돌로도 고생했습니다. 하지만 매번 로컬에서 빌드를 시도했기에 그 자리에서 바로 수정할 수 있었습니다. 만약 로컬 테스트 없이 GitHub에 푸시했다면, GitHub Actions 로그를 찾아서 분석하고, 다시 수정하고, 푸시하는 악순환에 빠졌을 것입니다.

특히 Chirpy 테마의 경우 특정 플러그인이 필수인데, 로컬 환경이 제대로 설정되지 않으면 이런 의존성 문제를 미리 캐치할 수 있습니다. bundle exec jekyll build 명령어로 실제 빌드 과정을 실행해보면, 배포 전에 모든 문제를 발견하고 해결할 수 있습니다.

지금 당신이 Jekyll과 GitHub Pages로 블로그를 운영하고 있거나 시작하려고 계획 중이라면, 오늘부터라도 로컬 빌드 환경을 제대로 구성하고 매 포스트마다 로컬에서 먼저 확인한 후 배포하는 습관을 들여보세요. 이것이 블로그의 품질을 높이는 가장 확실한 방법입니다.