GitHub Pages로 Jekyll 블로그를 운영하다 보면 한 번쯤은 이런 상황을 겪어보셨을 겁니다. 분명 새 글을 올렸는데 브라우저에서는 계속 옛날 내용만 보이고, 새로고침을 아무리 해도 "--- layout: home ---" 같은 이상한 텍스트만 나타나는 현상 말이죠. 저도 최근에 이 문제로 몇 시간을 허비했는데, 결국 원인을 찾아서 깔끔하게 해결했습니다.
문제의 원인: PWA와 브라우저 캐시
이 현상의 문제는 두 가지입니다. 첫 번째는 PWA(Progressive Web App) 기능이고, 두 번째는 브라우저의 강력한 캐시 정책입니다. hirpy 테마 같은 최신 Jekyll 테마들은 기본적으로 PWA를 활성화시켜 놓는데, 이게 블로그 업데이트를 방해하는 주요 원인이 됩니다.
PWA는 웹사이트를 마치 앱처럼 작동하게 만들어주는 기술입니다. 오프라인에서도 페이지를 볼 수 있게 해주는 장점이 있지만, 그만큼 캐시를 강력하게 유지하기 때문에 새로운 내용이 즉시 반영되지 않는 단점도 있습니다. 새로 Push 해서 CI/CD까지 완료되었는데 "업데이트가 있습니다. 새 콘텐츠를 보시겠습니까?"라는 팝업이 계속 뜨는 것도 바로 이 PWA 때문입니다.
해결 방법 1: PWA 비활성화하기
먼저 할 일은 PWA 기능을 끄는 것입니다. _config.yml 파일을 열어서 다음 부분을 수정해주세요.
pwa:
enabled: false # true에서 false로 변경
cache:
enabled: false # 마찬가지로 false로 변경이렇게 하면 더 이상 성가신 업데이트 팝업이 나타나지 않습니다. 물론 오프라인에서 블로그를 볼 수 없게 되지만, 솔직히 개인 블로그에서 오프라인 기능이 그렇게 중요한가요? 최신 콘텐츠를 제대로 보여주는 게 훨씬 중요합니다.
해결 방법 2: 브라우저 캐시 완전 차단
PWA를 비활성화해도 브라우저 자체 캐시 때문에 여전히 문제가 발생할 수 있습니다. 이것도 완전히 해결하려면 _includes/head.html 파일을 수정해야 합니다.
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="0">
<!-- 기존 내용들 -->
</head>head 태그아래에 위 4개의 메타태그를 넣습니다. 각 메타태그의 역할을 간단히 설명하자면, Cache-Control은 최신 브라우저를 위한 캐시 방지 설정이고, Pragma는 구형 브라우저 호환을 위한 것입니다. Expires는 캐시를 즉시 만료시키는 역할을 합니다. 이 세 가지를 모두 적용해야 거의 모든 브라우저에서 캐시 문제를 방지할 수 있습니다.
변경사항 적용하기
git add _config.yml _includes/head.html
git commit -m "fix: disable PWA and prevent browser caching"
git push origin 본인브랜치모든 수정이 끝났다면 Git으로 커밋하고 푸시해야 합니다.
커밋 메시지는 나중에 변경사항을 추적하기 쉽도록 명확하게 작성하는 게 좋습니다.
이렇게하면 모든 수정사항이 반영되어 글을 작성하면 즉시 반영됩니다.