리뉴얼 CSS가 유저에게 안 보이던 캐시 문제 해결

리뉴얼된 CSS를 배포했는데, 유저들의 브라우저에는 여전히 구 버전 스타일이 떠 있었다. 원인은 Cloudflare의 7일 immutable 캐시였다. 캐시버스터를 추가해 무효화했다.

배포했는데 왜 안 바뀌나

말이 안 되는 상황이었다. 로컬에서도 확인됐고, 스테이징 환경에서도 깔끔한 리뉴얼 스타일이 떴다. 그런데 프로덕션에 나간 순간부터 유저들이 보는 화면은 여전히 구 CSS였다. 개발팀은 최신 파일을 서빙하고 있는데, 뭔가 중간에서 막혀 있는 느낌이었다.

처음엔 배포 과정을 의심했다. 몇 번 재배포해봤지만 다를 바 없었다. 유저들 중 강력 새로고침(Ctrl+Shift+R)을 한 사람들은 새 스타일을 볼 수 있었지만, 그걸 일일이 안내할 순 없는 노릇이었다. 무언가 시스템 레벨에서 일어나고 있었다.

프로덕션 환경은 Cloudflare를 CDN으로 쓰고 있었고, 정적 자산(CSS 포함)에 대해 7일짜리 immutable 캐시 정책이 걸려 있었다. 이 정책은 합리적이다:

문제는 우리가 styles.css 라는 같은 파일명으로 계속 배포하고 있었다는 것이다. 캐시는 "이 파일은 절대 변하지 않아" 라고 믿고 7일을 기다린다. 리뉴얼이든 버그 픽스든, 콘텐츠가 진짜 바뀌었어도 캐시 입장에선 신경 쓰지 않는다.

해결책은 간단했다: URL을 바꾼다.

/* Before */
<link rel="stylesheet" href="/styles.css">

/* After */
<link rel="stylesheet" href="/styles.css?v=20260622a">

쿼리 스트링을 추가하면 CDN 입장에서는 완전히 다른 URL이다. 캐시가 없으니 서버에서 최신 파일을 가져온다. 첫 유저는 약간의 네트워크 대기를 겪지만, 그 이후로는 새로운 쿼리 스트링으로 다시 7일 캐시에 들어간다.

Base.astro 파일에 이 쿼리 스트링을 적용했고, 즉시 유저들에게 리뉴얼 CSS가 보였다.

이번 일을 통해 깨달은 점들:

첫째, CDN 캐시 정책은 배포 전략과 짝을 이룬다. Immutable 캐시는 훌륭한 성능 최적화지만, 파일명이 변하지 않으면 무용지물이다. 우리 팀은 이 부분을 간과했다. 정적 자산 버전 관리에 대한 명확한 규칙이 없었기 때문이다.

둘째, 리뉴얼 같은 큰 변화는 사전에 계획해야 한다. 배포 시점에 캐시 무효화 전략을 함께 고려하는 체크리스트가 필요하다:
- CDN 캐시 정책은?
- 클라이언트 캐시도 고려했나?
- 캐시버스터 버전 형식은?
- 이전 버전은 언제까지 서빙할 건가?

셋째, 이런 경험을 팀과 공유하는 게 중요하다. 다음 번 리뉴얼이나 주요 배포는 이번 경험이 밑바탕이 되어 훨씬 스무스할 것 같다.

캐시는 성능의 친구이면서 동시에 배포의 적이다. 둘을 적절히 균형 맞추는 게 팀 리딩의 기술이 아닐까 싶다.

🛒 이 글과 어울리는 추천 상품

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.