GitHub Pages 배포 실패? Jekyll 빌드 캐시 때문입니다

서론: 은퇴 후 블로깅을 시작하며 겪은 난감한 상황

저는 30년간 대학에서 컴퓨터공학을 가르친 교수입니다. 은퇴 후 블로깅을 통해 지난 세월 동안 축적한 지식을 나누고 싶어 Jekyll과 GitHub Pages로 개인 블로그를 구축하기로 결심했습니다. 처음에는 설치하고 로컬에서 테스트할 때 완벽하게 작동했습니다. 그런데 GitHub에 푸시하면 스타일이 깨지거나 새 글이 반영되지 않는 황당한 상황이 벌어졌습니다. 당시 저는 자동 배포가 제대로 이루어졌다고 생각했지만, 실제로는 GitHub Pages의 빌드 캐시 때문에 이전 버전의 사이트가 계속 배포되고 있었던 것입니다.

이 문제를 해결하는 데 며칠을 소비한 후, 저는 그 과정에서 배운 중요한 교훈들을 문서화하기로 했습니다. 오늘 여러분과 공유하는 이 팁들이 혹시 같은 상황에서 헤매고 계신 분들에게 큰 도움이 될 것이라 확신합니다.

Jekyll 빌드 캐시란 무엇인가

Jekyll은 정적 사이트 생성기로, 마크다운 파일을 HTML로 변환할 때 성능을 높이기 위해 캐시 메커니즘을 사용합니다. 로컬 환경에서는 .jekyll-cache 디렉토리가 생성되어 이전 빌드 결과를 저장합니다. GitHub Pages도 비슷한 방식으로 작동하는데, 문제는 이 캐시가 예상치 못하게 오래된 데이터를 제공할 수 있다는 점입니다.

제 경험상, 가장 흔한 시나리오는 다음과 같습니다. 포스트를 수정해서 푸시했는데 GitHub Pages가 여전히 이전 버전을 보여줄 때입니다. 브라우저 캐시 문제라고 생각하고 강력 새로고침(Ctrl+Shift+R)을 시도해도 변화가 없습니다. 이것이 바로 Jekyll의 빌드 캐시 때문인 경우가 대부분입니다. 특히 CSS 파일이나 레이아웃 파일을 수정했을 때 이런 현상이 심하게 나타나곤 했습니다.

해결책 1: 로컬에서 캐시 정리하기

가장 간단하고 효과적인 방법은 로컬 환경에서 빌드하기 전에 캐시를 완전히 삭제하는 것입니다. 터미널을 열고 블로그 루트 디렉토리로 이동한 후 다음 명령어를 실행하세요.

rm -rf .jekyll-cache
rm -rf _site

저는 이 명령어를 실행한 후 다시 로컬 서버를 시작합니다.

bundle exec jekyll serve

이렇게 하면 Jekyll은 처음부터 완전히 새로운 빌드를 수행합니다. 로컬에서 의도한 대로 작동하는 것을 확인한 후에 GitHub로 푸시하는 것이 중요합니다. 저는 이제 매번 주요 수정 사항이 있을 때마다 이 과정을 거치는 습관을 들였습니다. 처음에는 번거로웠지만, 이것이 얼마나 중요한지 깨닫고는 자동화도 고려해봤습니다.

해결책 2: GitHub Pages 빌드 캐시 무효화하기

로컬에서 캐시를 정리했는데도 GitHub Pages에서 여전히 이전 버전이 보인다면, GitHub 측의 캐시도 무효화해야 합니다. 가장 확실한 방법은 저장소의 설정을 건드리는 것입니다.

저장소 페이지에서 Settings로 이동한 후 Pages 섹션을 찾으세요. 소스 설정을 확인하고, 만약 변경할 사항이 없더라도 페이지를 저장하면 GitHub는 캐시를 무효화하고 새로 빌드합니다. 또 다른 방법은 깃허브 액션을 이용하는 것인데, .github/workflows 디렉토리에서 빌드 워크플로우를 확인하고 필요시 수동으로 다시 실행할 수 있습니다.

저는 더 적극적인 접근으로 repository를 트리거하는 방법도 사용합니다. 예를 들어 README 파일에 공백을 추가한 후 푸시하면 GitHub Pages가 강제로 재빌드되도록 할 수 있습니다. 이 방법은 긴급한 상황에서 매우 유용했습니다.

결론: 작은 습관이 만드는 큰 차이

지난 몇 개월간의 블로깅 경험을 통해 저는 한 가지 깨달았습니다. 기술적인 문제의 90%는 사전 예방으로 해결할 수 있다는 점입니다. 캐시 관리도 마찬가지입니다. 매번 빌드 전에 캐시를 정리하는 작은 습관이, 결과적으로 몇 시간의 디버깅 시간을 절약해줍니다. 혹시 당신도 GitHub Pages에서 예상치 못한 문제로 고민하고 있다면, 먼저 캐시를 의심해보시길 권합니다. 오늘 소개한 해결책들이 여러분의 블로깅 여정을 한층 수월하게 만들기를 바랍니다.

지금 바로 본인의 Jekyll 프로젝트에서 캐시를 정리하고 재배포해보세요. 당신의 블로그도 분명 더 빠르고 정확하게 업데이트될 것입니다.