JavaScript と CSS のキャッシュ更新：ファイル名、バージョン、安全な公開
キャッシュ更新では、変更した JavaScript や CSS に新しい URL を与えます。代表例は内容ハッシュを含むファイル名です。固定内容の資源は長くキャッシュし、HTML は短い有効期間か再検証で新しい参照を発見できるようにします。
このガイドの内容
プライベートウィンドウでは新しく、再訪者には古く見えるなら、全体の設定を変える前に資源 URL を比較します。サーバー上のファイルが置き換わっていても、ブラウザーには古い URL の新鮮な応答が残っている可能性があります。
安定した公開では HTML と資源の対応を明確にします。以下は新旧両方のファイルを残し、公開前に開かれたページが対応資源を取得できる例です。ハッシュ名は説明用で、実ファイルから算出した値ではありません。
HTML 文書とバージョン付き資源を分ける
HTML を公開版を指す小さな一覧と考えます。A は app.4c21.js と site.19ab.css を参照し、B でアプリを変えたら app.9d80.js を参照します。CSS のバイトが変わらなければ site.19ab.css はそのままです。内容が同じ資源は同じ URL を再利用します。
変更した資源は新しいキャッシュ上の識別子を持ちます。一方、HTML を長期間保存すると、訪問者は古い文書から古い URL を要求し続けます。更新の発見経路を確認することが大切で、サーバーに新しいスクリプトがあるだけでは十分ではありません。
| 資源 | 公開版 A | 公開版 B | 想定する扱い |
|---|---|---|---|
| HTML 文書 | app.4c21.js を参照 | app.9d80.js を参照 | 再検証か意図した短い有効期間 |
| アプリのスクリプト | app.4c21.js | app.9d80.js | バイトが変われば新 URL |
| 未変更の CSS | site.19ab.css | site.19ab.css | 同じ内容 URL を再利用 |
| 旧資源 | 利用可能 | 旧ページ向けに維持 | 必要な互換期間は保持 |
キャッシュ指示を資源の契約に合わせる
公開された内容バージョン付き資源で、その URL の内容を変更しないなら、長い max-age と immutable が適する場合があります。HTML の no-cache は保存を許しつつ再利用前の検証を要求します。no-store は保存しない要求で、意味が異なります。同じヘッダーをサイト全体にコピーしないでください。
次のヘッダーは方針の例です。ホスティングが実際に送る値と、エッジキャッシュ設定を確認します。ローカル設定ファイルに値が書かれていても、公開応答でブラウザーと CDN が同じ指示を受けた証拠にはなりません。
Versioned public asset: /assets/app.9d80.js
Cache-Control: public, max-age=31536000, immutable
HTML document: /index.html
Cache-Control: no-cache
The URL /assets/app.9d80.js must continue to serve the same bytes.クエリによる版管理はキャッシュキーを確認する
/app.js?v=release-b は /app.js?v=release-a と異なる識別子にできます。ただし関連キャッシュがそのパラメーターをキーに含めることが前提です。CDN がクエリを無視するルールなら、両方が同じオブジェクトに当たり、意図した版分離が失われます。
読み込みごとにランダムな値を付けると、有効な再利用がなくなります。安定した内容ハッシュや公開版は、資源が変わるときだけ変えます。/app.js#release-b のようなフラグメントは HTTP 要求に送信されないため、この用途には使えません。
古いバイトを返す層を特定する
影響を受けた訪問者について、HTML 応答、参照 URL、実際の資源バイトを比較します。文書が旧ハッシュを参照するなら HTML の鮮度、新ハッシュで旧内容が来るなら公開処理、キャッシュキー、オリジン応答を調べます。通信が正しいのに挙動が古い場合は、動作中ページやサービスワーカーも確認します。
CDN のパージは、全訪問者のブラウザーに保存済みの新鮮な応答を消しません。ハードリロードもローカル診断であり、全員の公開手順の修正ではありません。各テストでどのキャッシュを迂回したかを記録し、成功した理由を再現可能にします。
- 最終 HTML URL と参照されたスクリプトや CSS の URL を記録する。
- 状態、Content-Type、Cache-Control、ETag、利用可能なキャッシュ状態ヘッダーを調べる。
- 目的の版が HTML フォールバックではなく所定のバイトを返すか確認する。
- サービスワーカーがある場合はそのキャッシュ規則も別に調べる。
- 新規アクセスと、公開をまたいで開いたままのページを両方試す。
公開とロールバックで旧ページを壊さない
新資源を先にアップロードしてから参照 HTML を公開するか、完全な版を一括切替できる仕組みを使います。古い HTML と開いたタブが利用する期間は旧資源を残します。最初のアクセスから時間がたってから追加モジュールを読み込むページもあります。
例えば A と B の資源を両方含めて B を公開し、検証後も HTML を A に戻せるようにします。app.4c21.js を直ちに削除すると A の文書を持つ人が失敗します。同じハッシュ名を新内容に使い回すことも内容識別の契約を破り、復旧を不確実にします。
正しさを確認してから再利用を測る
最初の訪問で資源を取得し、再訪で適切に再利用し、新版では変更資源だけを取得するか小さく検証します。再検証要求も含めて通信を観察し、キャッシュに関係する応答をすべて同じとみなさないようにします。
キャッシュ節約計算機は、自分で入力したヒット率の仮定からオリジン要求削減を見積もります。転送計算機は件数と応答サイズからバイト数を求めます。どちらも公開ヘッダーと実測ヒット率の代わりではなく、更新が正しく機能した後の計画比較に使います。
比較記録では、ブラウザー再利用、エッジのヒット、オリジンからの応答を区別します。減ったものが利用者への転送なのか、エッジからオリジンへの要求なのかで意味が変わります。開発者ツールでキャッシュを無効にした検証を、通常の再訪体験と混同しないことも大切です。
よくある質問
古い CSS を直すために全キャッシュを無効にしますか？
まず古い文書か資源を特定し、安定した版管理を作ります。全体の再利用を止めると通信と遅延が増え、公開手順の不明確さが残る場合があります。
ETag を変えれば新鮮なキャッシュも直ちに置換されますか？
ブラウザーは新鮮な応答をサーバー確認なしで再利用できます。内容変更時の新 URL は、その後の検証まで更新発見を待つ必要を避けます。
公開直後に旧ハッシュ資源を消してもよいですか？
保存済み HTML、開いたページ、ロールバックに必要な互換期間を考慮します。対応する文書が参照し得る間は旧ファイルを保持します。
出典と定義
計算方法の確認日: