Jekyll 블로그 빌드가 자꾸 멈춘다면? 이미지 변환 작업 최적화 가이드

은퇴 후 시작한 기술 블로그의 예상치 못한 문제

작년 봄, 저는 30년간의 직장 생활을 마감하고 평소 관심 있던 기술 지식을 공유하기 위해 Jekyll 블로그를 시작했습니다. GitHub Pages로 호스팅하면 비용도 없고, 마크다운으로 편하게 글을 쓸 수 있다는 점이 매력적이었거든요. 처음 몇 개월은 순조로웠습니다. 그런데 포스팅이 늘어나면서 이상한 현상이 나타났습니다. 빌드가 진행 중이라는 메시지 후 몇 시간이 지나도 배포가 되지 않는 것입니다. 특히 사진이 많은 포스팅을 올릴 때마다 이 문제가 반복되었습니다.

GitHub의 로그를 확인해보니 “image transformation” 작업에서 프로세스가 멈춰 있었습니다. 많은 시니어 개발자나 블로거들이 저와 같은 문제를 겪고 있었고, 이는 Gatsby와 Jekyll 같은 정적 사이트 생성기의 흔한 이슈였습니다. 몇 주간의 시행착오 끝에 문제를 해결했고, 지금부터 제 경험을 공유하겠습니다.

왜 이미지 변환에서 빌드가 멈출까?

Jekyll과 Chirpy 테마를 사용할 때, 블로그는 업로드된 이미지를 자동으로 여러 크기의 버전으로 변환합니다. 데스크톱, 태블릿, 모바일 등 다양한 기기에 최적화된 이미지를 제공하기 위함입니다. 이 과정이 상당한 시스템 리소스를 소비합니다.

특히 고해상도 사진을 많이 업로드하거나, 한 번에 여러 포스팅을 올릴 때 문제가 심해집니다. GitHub Actions의 빌드 환경은 제한된 CPU와 메모리를 갖고 있어서, 복잡한 이미지 변환 작업이 타임아웃되거나 멈추기 쉬운 구조입니다. 제 경우, 해외 여행 사진 포스팅을 올릴 때 40장 이상의 고해상도 이미지를 포함했는데, 그날따라 빌드가 완전히 중단되어 버렸습니다.

문제의 근본 원인은 다음과 같습니다. 첫째, 이미지 파일의 크기가 너무 큽니다. 둘째, 변환 과정에서 메모리 누수가 발생할 수 있습니다. 셋째, GitHub Actions의 기본 타임아웃 설정이 길지 않다는 점입니다.

실전 해결책: 이미지 최적화 3단계

1단계: 업로드 전 이미지 압축하기

가장 기본적이면서 가장 효과적인 방법입니다. 저는 이제 모든 이미지를 온라인 압축 도구나 로컬 도구로 처리합니다. 저는 ImageMagick을 사용해서 배치 처리로 이미지를 최적화합니다. 권장 해상도는 1200px 너비 정도면 충분합니다. 원본 이미지가 5MB였다면 압축 후 300KB~500KB 수준으로 줄일 수 있습니다. 이것만으로도 빌드 시간이 절반으로 단축되었습니다.

2단계: Jekyll 설정 파일 조정하기

_config.yml 파일에서 이미지 변환 관련 설정을 수정합니다. 변환해야 할 이미지 크기를 줄이거나, 특정 포스팅에서는 이미지 변환을 비활성화할 수 있습니다. Chirpy 테마의 경우 compress_images 옵션을 조정하면 됩니다. 저는 모바일용 소형 이미지는 생략하고 두 가지 크기만 유지하도록 설정했습니다.

3단계: 로컬 빌드로 사전 검증하기

GitHub에 올리기 전에 로컬 환경에서 완전히 빌드를 마쳐봅니다. jekyll serve 명령으로 모든 이미지 변환이 정상적으로 작동하는지 확인합니다. 이렇게 하면 GitHub Actions에서 실패할 일이 거의 없습니다.

지금 바로 적용해보세요

지금까지 빌드 시간이 길어서 답답하셨다면, 위의 세 가지 방법을 순서대로 적용해보시기 바랍니다. 먼저 이미지 압축부터 시작하면, 특별한 기술 지식 없이도 즉각적인 효과를 볼 수 있을 것입니다. 저처럼 은퇴 후 취미로 블로그를 운영하시는 분이라면, 이 문제가 해결되었을 때의 쾌감이 말로 표현할 수 없을 정도입니다. 댓글로 여러분의 경험담을 나눠주시면 좋겠습니다.