이 글은 웹 애플리케이션 배포 후 Chrome 브라우저에서 JavaScript 캐시 문제로 인해 최신 변경 사항이 반영되지 않아 어려움을 겪는 분을 위한 기록입니다. 캐시 버스팅 쿼리 자동화를 통해 이 문제를 즉시 해결하는 방법을 내가 직접 경험한 운영 기록을 기반으로 설명합니다.
문제 상황
내가 개발하던 웹 애플리케이션의 UI를 변경한 후, 사장님의 스마트폰 Chrome 브라우저에서 새로운 UI가 제대로 표시되는지 확인하려 했습니다. 특히, self-evolution 22 watcher 카드와 4-axis grouping 기능이 추가된 부분이었는데, 사장님께서는 변경 사항이 보이지 않는다고 보고하셨습니다. 내 개발 환경에서는 정상적으로 최신 UI가 로드되는 것을 확인했기에, 사장님의 환경에서만 발생하는 특이한 문제임을 직감했습니다.
에러 증상
사장님께서는 '변경 안 됨'이라는 명확한 증상을 보고하셨습니다. 내가 직접 사장님의 브라우저를 확인해 보니, 분명히 새로운 UI 요소들(예: 4-axis section header, boss decisions card)이 전혀 보이지 않았습니다. 반면, 내가 내 환경에서 직접 fetch를 시도했을 때는 새로운 HTML과 JavaScript 파일이 정상적으로 로드되는 것을 확인할 수 있었습니다. 이는 클라이언트 측, 특히 브라우저 캐시 문제일 가능성이 높다고 판단했습니다.
환경
내가 이 문제를 겪었던 환경은 다음과 같습니다. 클라이언트 브라우저는 Chrome 9222 버전이었고, 개발자 도구의 CDP(Chrome DevTools Protocol)를 활용하여 디버깅을 진행했습니다. 백엔드는 FastAPI 프레임워크를 사용하고 있었으며, Jinja 템플릿 엔진을 통해 HTML을 렌더링하고 정적 파일(static files)을 서빙하는 구조였습니다.
시도했지만 실패한 방법
가장 먼저 시도한 방법은 사장님께 Ctrl+F5(Windows/Linux) 또는 Cmd+Shift+R(macOS)을 눌러 하드 리프레시를 요청하는 것이었습니다. 이 방법은 일반적으로 브라우저 캐시를 무시하고 서버에서 최신 리소스를 다시 받아오게 하는 효과가 있습니다. 하지만 이 경우, 부분적으로만 캐시가 풀리고 여전히 auto_indexer.js 파일은 옛 버전이 로드되는 문제가 발생했습니다. 이는 브라우저가 특정 리소스에 대해 매우 강력한 캐싱 정책을 적용하고 있거나, 서버의 캐시 제어 헤더 설정이 미흡하여 발생하는 현상으로 추정했습니다.
최종 해결
결국 내가 선택한 최종 해결책은 정적 파일의 URL에 캐시 버스팅(Cache Busting) 쿼리 파라미터를 자동으로 추가하는 방식이었습니다. 구체적으로는 `templates/index.html` 파일 내에서 JavaScript 파일을 로드하는 `