2 min read · 468 words
웹앱 배포 후 특정 모바일 기기나 브라우저에서 변경 사항이 즉시 반영되지 않아 곤란을 겪는 개발자들을 위한 글이다. 이 글에서는 강력 새로고침으로도 해결되지 않는 고질적인 Chrome JS 캐시 문제를 빌드 타임 cache-bust 쿼리 스트링 적용으로 즉각 해결하는 방법을 다룬다.
문제 상황
운영 기록 기준, 내가 웹앱 UI를 변경한 후 사장님 스마트폰의 Chrome 브라우저에서 새 UI가 정상적으로 노출되는지 확인하려고 했다. 하지만 사장님 화면에서는 self-evolution 22 watcher 카드와 4-axis grouping 영역이 전혀 보이지 않는 현상이 발생했다. 내 로컬 환경과 Claude가 fetch한 결과에서는 새 HTML 마크업이 정상적으로 반환되고 있었기에 당황스러웠다.
에러 증상
정확한 에러 메시지는 없었으나, 사장님 본인 기기에서만 "UI 변경 사항이 전혀 반영되지 않았다"는 피드백이 지속적으로 접수되는 증상이 있었다. 정확한 원인은 추가 확인이 필요하지만, 현재 확인된 원인은 다음과 같습니다. 사장님 기기의 Chrome 브라우저가 기존에 로드했던 옛날 버전의 스크립트 파일(auto_indexer.js?v=20260508)을 강하게 캐싱하고 있어, 서버의 최신 마크업과 구형 JS가 충돌하여 렌더링이 누락된 상태였다.
사장님이 "개발팀 일 안 하냐"고 눈치를 주실 때 식은땀이 흘렀지만, 내 화면에선 너무나 잘 되고 있어서 억울함이 밀려왔다.
환경
OS 및 브라우저: Chrome 9222 CDP 환경 및 모바일 Chrome
백엔드 프레임워크: FastAPI Jinja static file serving
Chrome JS 캐시 해결을 위해 시도했지만 실패한 방법
내가 가장 먼저 시도한 것은 사장님 기기에서 Ctrl+F5를 통한 강력 새로고침(Hard Refresh)이었다. 하지만 이 방법은 HTML 문서 자체만 새로 받아올 뿐, 내부에 포함된 정적 자산인 JS 파일의 캐시는 부분적으로만 풀리고 완전히 갱신되지 않아 실패했다.
최종 해결
결국 브라우저가 캐시를 강제로 무시하도록 만드는 가장 확실한 방법인 cache-bust 쿼리 스트링 자동 갱신 기법을 도입했다. templates/index.html 파일 내부에서 참조하는 정적 파일 경로 뒤의 버전 쿼리를 매 배포 또는 세션 변경 시마다 고유한 값으로 자동 bump하도록 수정했다. 기존 ?v=20260508-sess47-... 형태에서 ?v=20260523-sess141-cycle42-autorefresh와 같이 변경 사항이 발생할 때마다 새 쿼리를 붙여 브라우저가 완전히 새로운 파일로 인식하게 만들었다.
사용한 코드
<!-- Jinja 템플릿 내 정적 파일 호출 시 고유 세션 및 카테고리 쿼리 적용 -->
<script src="/static/js/writer.js?v=20260523-sess142-category-doctrine"></script>검증 결과
내부 테스트 기준, Chrome MCP find 도구를 활용하여 사장님 기기 환경을 시뮬레이션하고 새 마크업(4-axis section header, boss decisions card)이 정상적으로 로드되는지 확인했다. 총 6개 검증 항목 중 6개 모두 visual confirm을 완료했다.
현재 상태
현재 상태는 fixed로, 더 이상 이전 캐시가 간섭하지 않고 최신 UI가 즉각 반영된다.
같은 문제 겪는 분들에게
사용자가 새로고침을 해도 화면이 깨지거나 옛날 UI가 보인다면, 브라우저의 Chrome JS 캐시 정책을 의심해야 한다. 사용자에게 새로고침을 요구하는 대신, 빌드 파이프라인이나 템플릿 엔진 단계에서 정적 파일 경로 뒤에 고유한 쿼리 스트링을 자동으로 붙여 배포하는 로직부터 점검하는 것을 강력히 권장한다.
Category Coverage Notice
This article follows our label-specific editorial criteria. Details: