블로그 빌드가 자꾸 멈춘다면? 이미지 변환 작업의 함정
Jekyll 블로그 빌드 중 이미지 변환 작업에서 무한 대기 현상이 발생하는 원인과 해결책
퇴임 후 취미로 시작한 기술 블로그의 불청객
30년간 대학에서 전산학을 가르쳤던 나는 퇴임 후 GitHub Pages와 Jekyll로 개인 블로그를 운영하기로 결심했다. 처음엔 매우 순조로웠다. 마크다운으로 글을 작성하고, 커밋하면 자동으로 빌드되어 배포되는 마법 같은 경험이었다. 하지만 몇 달 뒤, 예상치 못한 문제가 나타났다. 블로그 빌드가 자꾸만 멈춰 버린 것이다.
최근 GitHub 공식 이슈 추적 시스템에서 발견한 사례를 보니, 이것은 나만의 문제가 아니었다. 수많은 개발자들이 같은 곤경에 처해 있었다. 특히 “Build stuck at running jobs (image transformation)”라는 이슈는 정확히 내가 겪던 상황을 묘사하고 있었다. 이미지 변환 작업에서 빌드가 무한 대기 상태에 빠지는 현상이었다.
문제의 원인: 이미지 처리 파이프라인의 복잡성
Jekyll과 GitHub Pages의 빌드 시스템은 기본적으로 매우 효율적이다. 하지만 블로그에 포함된 이미지의 개수와 크기가 증가하면서 상황이 달라진다. 특히 다양한 크기와 포맷으로 이미지를 최적화하려는 플러그인들을 사용할 때 문제가 발생하기 쉽다.
내가 겪은 구체적인 상황을 설명하자면, 나는 과거 강의 자료와 실습 사진들을 블로그에 올리기 시작했다. 고해상도 스캔본들과 다양한 형식의 이미지들이 섞여 있었다. jekyll-picture-tag나 다른 이미지 최적화 플러그인들이 이 모든 이미지를 WEBP 포맷으로 변환하고, 여러 해상도의 썸네일을 생성하려다 보니 빌드 프로세스가 몇 시간을 넘게 소비하게 되었다.
더 심각한 문제는 GitHub Actions의 타임아웃이었다. 기본적으로 GitHub Pages 빌드는 36분 안에 완료되어야 한다. 이미지 변환 작업이 이 제한 시간을 초과하면 빌드는 실패로 표시되고, 블로그는 업데이트되지 않는다. 마치 시간이 정해진 시험인데, 계산기가 자꾸 먹통이 되는 것과 같은 답답함이었다.
실질적인 해결 방안들
첫 번째 방법은 사전 최적화다. 블로그에 업로드하기 전에 이미지를 미리 처리하는 것이다. ImageMagick이나 Squoosh CLI 같은 도구를 로컬 환경에서 먼저 실행해 이미지 크기를 줄이고 포맷을 변환한다. 내 경우, 원본 이미지 크기를 평균 60% 줄이는 것만으로도 빌드 시간을 절반 이상 단축할 수 있었다.
두 번째 방법은 플러그인 재검토다. 모든 자동화가 필요한 것은 아니다. 나는 불필요한 이미지 변환 플러그인들을 과감히 제거했다. GitHub Pages가 공식 지원하는 제한된 플러그인 목록만 사용하기로 결정했다. 이렇게 하니 빌드 시간이 극적으로 단축되었다.
세 번째는 로컬 빌드 자동화의 활용이다. GitHub Actions만 의존하지 말고, 로컬 환경에서 먼저 전체 빌드를 테스트하는 습관을 들였다. jekyll build 명령어를 실행할 때 문제가 없으면, GitHub에 푸시해도 대부분 성공한다. 이것은 마치 교수 시절 시험지를 출제한 후 직접 풀어보는 것처럼, 기본적이지만 매우 효과적인 방법이다.
마지막으로는 빌드 로그 분석이다. GitHub Actions의 빌드 로그를 자세히 읽으면, 정확히 어느 단계에서 시간이 오래 걸리는지 알 수 있다. 내 경우 특정 포스트의 이미지들이 병목이었고, 그 포스트의 이미지들만 재처리하는 것으로 해결되었다.
기술자의 경험에서 얻은 교훈
지난 30년 학계에서 배운 것이 하나 있다면, 자동화는 축복이지만 과도한 자동화는 독이 될 수 있다는 것이다. Jekyll도 마찬가지다. 멋진 플러그인들이 많지만, 각각의 플러그인이 빌드 프로세스에 어떤 영향을 미치는지 이해하고 사용해야 한다.
또한 문제 해결의 첫 번째 단계는 항상 로깅과 모니터링이다. GitHub Pages와 Jekyll의 빌드 과정을 투명하게 드러내어 무엇이 느린지 파악하는 것이 가장 중요하다. 만약 지금 당신의 블로그 빌드가 멈춰 있다면, 로그를 확인하고, 불필요한 플러그인을 제거하며, 이미지부터 최적화해 보길 권한다. 그 간단한 조치만으로도 대부분의 문제는 해결될 것이다.
혹시 비슷한 문제를 겪고 계신가요? 댓글로 당신의 빌드 시간과 사용 중인 플러그인들을 공유해 주신다면, 더 구체적인 조언을 드릴 수 있을 것 같습니다.