CDN 캐시 무효화 실패로 구버전 콘텐츠가 사용자에게 계속 보이는 문제의 진단과 캐시 전략 재설계

긴급 버그 픽스 배포 후 서버 쪽 코드 변경과 정적 파일 배포가 완료됐음에도 상당수의 사용자들이 계속 구버전 UI와 구버전 API 응답을 받고 있다는 민원이 쏟아졌습니다. 엔지니어 노트북에서 직접 접속했을 때는 분명 최신 버전이 로드되었기 때문에 초반에는 사용자들의 로컬 브라우저 캐시 문제를 의심했습니다. 그러나 사용자들이 시크릿 창으로 접속해도 동일한 구버전이 나온다는 증언이 이어지면서 이것이 단순한 브라우저 캐시 문제가 아니라 CDN 레벨의 캐시 무효화 실패임을 깨달았습니다. Cloudflare CDN이 정적 자원들을 엣지 서버에 강하게 캐싱하고 있었습니다. 배포 시 CDN 캐시를 Purge(삭제)하는 자동화 스크립트가 CD 파이프라인에 포함되어 있었는데 조사해보니 이 스크립트가 특정 경로 패턴에 대한 파일만 무효화하도록 설계되었고 최근 새롭게 추가된 서브디렉터리의 파일들은 패턴에 포함되지 않아 캐시가 만료되지 않은 채 남아있었습니다. 구버전 JS 번들이 엣지 서버에서 전 세계 사용자들에게 계속 제공되고 있었던 것입니다. 근본적인 해결책은 캐시 무효화에만 의존하지 않는 캐시 버스팅(Cache Busting) 전략의 도입이었습니다. HTML 파일에서 CSS와 JS 파일을 불러올 때 파일명에 빌드마다 달라지는 해시값을 포함시키는 방법입니다. 예를 들어 app.js가 아니라 app.a3f8c2e.js처럼 배포 내용이 바뀔 때마다 파일명이 달라집니다. CDN은 이 파일명이 완전히 다른 새로운 자원으로 인식하고 새로운 파일을 원서버에서 받아와 저장합니다. 구버전 파일의 캐시를 일일이 지울 필요 없이 클라이언트가 최신 HTML을 받는 순간 자동으로 새 버전의 정적 파일을 요청하게 됩니다. Webpack과 Vite는 기본적으로 이 기능을 지원합니다. 빌드 파이프라인 설정에서 output.filename 패턴에 contenthash를 활성화하자 이후 어떤 배포에서도 구버전 캐시 문제가 재발하지 않았습니다.