Jekyll 블로그 이미지 변환에서 멈춰버린다면? 베테랑 개발자의 해결책

예순 세 살의 나이에 대학교 컴퓨터공학과를 정년퇴직한 후, 취미 삼아 개인 블로그를 운영하기 시작했습니다. GitHub Pages에 Jekyll을 올리고 꾸준히 글을 써오던 차에, 어느 날부터 갑자기 빌드가 진행되지 않는 현상이 발생했습니다. 로그를 살펴보니 “running jobs (image transformation)”에서 무한 대기 상태였습니다. 당시 당황했던 경험을 바탕으로, 같은 상황에 처한 시니어 개발자 분들을 위해 해결책을 공유하고자 합니다.

이미지 변환 작업에서 빌드가 멈추는 이유

Jekyll에서 GitHub Pages로 배포할 때, 이미지 파일들은 자동으로 최적화 과정을 거칩니다. 특히 최근 버전의 Jekyll에서는 WebP 형식으로의 자동 변환 기능이 추가되었는데, 이 과정에서 문제가 발생할 수 있습니다.

내 경우에는 수년간 모아둔 약 200개의 고해상도 사진이 있었는데, 이들이 동시에 처리되려다 보니 메모리 부족 문제가 발생했던 것 같습니다. 특히 1920x1080 이상의 고해상도 이미지가 많을수록 이 문제는 악화됩니다. GitHub Actions의 빌드 환경에서 할당된 메모리는 제한적이기 때문에, 대량의 이미지를 한꺼번에 처리하려면 타임아웃이 발생할 수밖에 없었던 것입니다.

또한 깨진 이미지 파일이나 손상된 메타데이터가 있는 이미지 파일도 이 문제의 원인이 될 수 있습니다. 여러 해에 걸쳐 수집한 이미지들 중에 어느 것이 문제를 일으키는지 찾아내는 것이 첫 번째 과제였습니다.

빠른 진단과 실용적인 해결책

첫 번째로 시도해야 할 방법은 _config.yml 파일에서 이미지 자동 변환 기능을 임시로 비활성화하는 것입니다. 다음 설정을 추가하세요:

image_processing:
  enabled: false

이렇게 하면 빌드가 정상적으로 완료되는지 확인할 수 있습니다. 만약 이 설정만으로도 빌드가 성공한다면, 문제는 이미지 변환 프로세스에 있다는 것이 확실합니다.

두 번째로는 _posts 디렉토리의 이미지 파일들을 체계적으로 정리해야 합니다. 저는 다음과 같은 순서로 진행했습니다:

1. 모든 이미지를 별도 폴더로 옮기기
2. 한두 개의 테스트 이미지만 남겨두기
3. 빌드 성공 확인 후 이미지를 하나씩 추가하기

이 방식으로 진행하면 어떤 이미지가 문제를 일으키는지 정확히 파악할 수 있습니다.

세 번째는 이미지 최적화를 수동으로 처리하는 것입니다. ImageMagick이나 JPEG 최적화 도구를 사용해 사전에 이미지 용량을 줄이고, 해상도를 1200x800 정도로 제한하면 빌드 시간이 대폭 단축됩니다. 블로그 용도로는 이 정도 해상도로도 충분하며, 사용자 경험도 오히려 더 좋아집니다.

장기적인 관리 전략

문제를 해결한 이후, 이런 상황이 반복되지 않도록 하는 관리 체계가 필요합니다. 저는 다음과 같은 정책을 수립했습니다:

먼저 새로운 이미지를 블로그에 업로드하기 전에 반드시 최적화 과정을 거칩니다. 온라인 도구인 TinyPNG나 ImageOptim을 사용해 용량을 50% 이상 줄이고, 가로 길이를 1200픽셀 이하로 조정합니다. 이는 빌드 속도뿐 아니라 블로그 로딩 속도 개선에도 큰 도움이 됩니다.

둘째, GitHub Actions 로그를 주기적으로 확인하는 습관을 들였습니다. 빌드가 완료되는 데 걸리는 시간을 추적하면, 미래에 문제가 발생할 조짐을 미리 알 수 있습니다. 시간이 점차 늘어나면 이미지 최적화를 더 강화해야 한다는 신호입니다.

셋째는 _config.yml 파일에서 이미지 변환 옵션을 보수적으로 설정하는 것입니다:

image_processing:
  enabled: true
  formats: [webp]
  cache: true

이렇게 하면 WebP 형식으로만 변환하고, 변환된 파일을 캐시해 반복 빌드 시 시간을 절약할 수 있습니다.

정년퇴직 후 개인 블로그를 취미 삼아 운영하면서 겪은 이 문제는 사실 기술적으로는 매우 일반적인 것입니다. 하지만 많은 시니어 개발자분들이 최근의 자동화 도구들의 한계를 모르고 문제를 겪고 있습니다. 저의 경험이 누군가에게는 소중한 시간을 아껴줄 수 있기를 바랍니다. 혹시 비슷한 문제로 고민 중이라면, 위 방법들을 순서대로 시도해 보시고 댓글로 결과를 공유해 주시면 더 많은 분들에게 도움이 될 것 같습니다.