本記事は、ウェブアプリのデプロイ後に特定のモバイル端末やブラウザで古いJavaScriptファイルがキャッシュされ、新しい機能が反映されない現象に悩む開発者に向けたものです。デプロイ後にいくらリロードしても解決しない、あの厄介なChromeモバイルのキャッシュ問題を、テンプレート側で確実に吹き飛ばす方法を共有します。
私が運用しているモジュールでウェブアプリの変更をデプロイした後、社長のスマートフォンのChromeブラウザで新しいUIが正常に表示されているか確認しようとした。今回のアップデートには、self-evolution 22 watcherカードと4-axis groupingビューが含まれていたのだが、社長の画面には古いレイアウトがぽつんと表示されているだけだった。資本主義社会において、コードが金（社長）に勝てるはずもない。私は即座にこのキャッシュ地獄を解決せねばならなかった。
エラーの状況
社長本人は、画面を何度リロードしても「何も変わっていない」と報告してきた。一方で、私がClaude環境から直接fetchを叩いてサーバーのHTMLを取得したところ、新しいマークアップは正常に返ってきていた。正確な原因はさらに調査が必要だが、現時点で判明している原因は、社長のモバイルChromeブラウザが以前ロードした auto_indexer.js?v=20260508 ファイルをメモリに強力にキャッシュしており、新しいスクリプトを読み込めない状態になっていることだった。
環境
- デバッグツール: Chrome 9222 CDP (Chrome DevTools Protocol)
- バックエンドフレームワーク: FastAPI (Jinja2 static file serving)
- 対象ブラウザ: モバイルChrome (Android/iOS)
試して失敗した方法
社長にモバイルChromeでの「強力な再読み込み（ハードリフレッシュ）」を試してもらったが、一部のリソースが部分的に更新されるだけで、肝心のJSファイルは依然として古いバージョンのキャッシュを保持し続けていた。モバイル環境の特性上、デスクトップのようにCtrl+F5をスマートに効かせることが難しく、ブラウザ設定の奥深くに入ってキャッシュを手動で削除してもらうというのは、ユーザー体験（UX）の観点から最悪の選択肢だった。
最終的な解決策
結局、クライアント側の手動操作に依存するのを諦め、サーバーがHTMLを返す際に静的ファイルのクエリ文字列（Query String）を強制的に変更する「キャッシュバスター（Cache-Busting）」方式を導入することにした。templates/index.html 内に宣言されているスクリプトパスの後ろのバージョンを、?v=20260508-sess47-... のような形式から、デプロイごとに固有のハッシュやセッションIDが結合された ?v=20260523-sess141-cycle42-autorefresh 形式へ自動的にバンプ（bump）するように修正した。これにより、ブラウザは完全に新しいURLとして認識するため、キャッシュを無視してサーバーから直接最新のJSファイルをダウンロードするようになる。
使用したコード
<!-- templates/index.html - デプロイ時にクエリパラメータを強制更新してキャッシュを無効化 -->
<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（解決済み）
同じ問題に直面している方へ
Chromeモバイルのキャッシュは、想像以上にしぶとい。ユーザーが自発的にリロードしてくれることを期待するのではなく、デプロイパイプラインやテンプレートレンダラーの段階で、静的ファイルのクエリ文字列を自動的にバンプするロジックを必ず構築しておくべきだ。特に、社長への報告直前であれば、この作業は選択ではなく必須である。
Category Coverage Notice
This article follows our label-specific editorial criteria. Details: