Jekyll 빌드가 자꾸 멈춘다면? 이미지 변환 작업의 함정

지난해 은퇴를 앞두고 여생의 기록을 남기기 위해 GitHub Pages에 Jekyll 블로그를 구축했습니다. 처음에는 마크다운 문법도 낯설고 셋업 과정도 복잡했지만, 대학원 시절 프로그래밍 기초가 있었던 탓에 차근차근 진행할 수 있었습니다. 그런데 몇 달이 지난 어느 날, 갑자기 빌드 프로세스가 멈춰버렸습니다. 시간이 자꾸 초과되고, GitHub Actions 로그에는 “이미지 변환 작업”이라는 메시지만 반복되었습니다. 그날부터 나는 이 문제를 해결하기 위해 소비한 대여섯 시간을 결코 잊을 수 없습니다.

빌드가 멈추는 현상, 원인은 이미지 처리

Jekyll 블로그를 운영하다 보면 마주하는 가장 흔한 문제 중 하나가 바로 빌드 과정에서의 무한 대기 상태입니다. 특히 이미지를 많이 포함한 포스팅을 추가한 후에 이런 증상이 나타난다면, 거의 확실하게 이미지 변환 프로세스에서의 병목 현상이라고 봐도 무방합니다.

공식 이슈 트래커에 보고된 사례들을 살펴보면, 대부분의 사용자들이 고해상도 이미지나 용량이 큰 사진 파일을 포스팅에 첨부한 후 이 문제를 경험했습니다. Jekyll의 이미지 처리 파이프라인, 특히 Chirpy 테마를 사용하는 경우 자동으로 여러 해상도의 썸네일을 생성하려고 시도하는데, 이 과정이 시스템 리소스를 과다하게 소비하거나 특정 이미지 포맷에서 오류가 발생하면 무한 루프에 빠지게 되는 것입니다.

나의 경우, 대학 시절 자료를 스캔한 PDF 파일을 JPEG으로 변환하여 업로드했는데, 이 변환 과정이 완전하지 않아 손상된 이미지 헤더를 가진 파일이 섞여있었습니다. Jekyll은 이 파일을 처리하려다가 계속 재시도하는 악순환에 빠졌던 것입니다.

문제 진단: 로그를 읽는 방법

GitHub Pages를 통해 블로그를 배포하고 있다면, Actions 탭에서 빌드 로그를 상세히 확인할 수 있습니다. 단순히 “실패했습니다”라는 메시지만 보고 지나가기 쉽지만, “Show all” 버튼을 눌러 전체 로그를 펼쳐봐야 합니다.

내 경험에 따르면, 이미지 변환 작업이 문제일 때는 보통 다음과 같은 특징이 있습니다. 첫째, 특정 단계(대개 “Running jobs” 섹션)에서 진행 표시기가 움직이지 않습니다. 둘째, 로그의 마지막 부분이 이미지나 GraphicsMagick 관련 메시지로 끝납니다. 셋째, 타임아웃 오류 메시지가 나타나면 그것이 명백한 신호입니다.

직접 로컬 환경에서도 같은 문제를 재현할 수 있습니다. 터미널에서 bundle exec jekyll build를 실행해보세요. 원격 서버보다 더 빠르게 어느 파일에서 걸리는지 파악할 수 있습니다. 제 경우 로컬에서 20분 이상 같은 이미지 파일을 반복 처리하는 것을 목격했고, 그제야 문제의 정체를 깨달았습니다.

해결책: 세 가지 접근 방식

첫 번째 방법은 이미지 사전 최적화입니다. 모든 이미지를 블로그에 업로드하기 전에 ImageMagick이나 온라인 이미지 컨버터를 사용해 정규화하세요. 해상도는 웹 표준인 72 DPI로 통일하고, 포맷은 JPEG이나 PNG 중 하나로 명확히 합니다. 너비는 1200픽셀 이상 2000픽셀 이하로 유지하면 충분합니다. 제 경우 JPEG 최대 품질 85%로 압축하니 이전보다 빌드 시간이 절반으로 줄어들었습니다.

두 번째는 의심 파일 제거 및 재업로드입니다. 빌드 로그에서 특정 이미지 파일이 반복되면, 그 파일을 임시로 repository에서 삭제하고 빌드를 시도해보세요. 정상 진행되면 그 파일이 원인이라는 뜻입니다. 그 후 해당 파일을 다시 변환하여 재업로드합니다.

세 번째는 Jekyll 설정 파일(_config.yml)에서 이미지 처리 옵션을 조정하는 방법입니다. Chirpy 테마를 사용한다면, 자동 이미지 최적화 기능을 일시적으로 비활성화할 수 있습니다. YAML 파일에 lazy_load_images: false를 추가하거나, 썸네일 생성 플러그인을 제거해볼 수 있습니다. 이는 최종 솔루션이 아니지만, 응급 상황에서는 유효합니다.

오래된 연구자의 입장에서 보면, 이 모든 과정은 데이터 검증의 기본 원칙과 다르지 않습니다. 투입하는 자료의 품질을 먼저 보장해야 시스템이 안정적으로 작동한다는 것이죠. 혹시 여러분도 Jekyll 블로그 빌드에서 같은 경험을 하고 계신가요? 위의 방법들을 순서대로 시도해보시고, 여러분만의 해결 경험을 댓글로 공유해 주시길 바랍니다.