Cache APIとService Workerキャッシュストレージの内部

caches.open(name) で得た Cache に put するだけ、と思われがちな Cache API には、「クエリ違いでヒットしない」「Vary のせいで取れない」「Cache-Control を付けたのに古いまま」「いつの間にか全部消えた」という事故の種が詰まっています。これらはすべて Cache Storage のキー照合アルゴリズムと、HTTP キャッシュからの独立性、そしてオリジン共有クォータの退避規則を知れば説明がつきます。ここではキーである Request の照合、Vary と部分応答、HTTP キャッシュとの違い、容量管理と退避を内部動作から見ていきます。

Cache Storage のデータモデル

Cache Storage は「名前付き Cache の集合」です。caches（CacheStorage）の下に複数の Cache がぶら下がり、各 Cache は Request をキー、Response を値とするエントリの列を保持します。素朴な Map と違うのは、キーが文字列ではなく Request オブジェクトであり、照合が後述の専用アルゴリズムで行われる点です。

const cache = await caches.open('static-v3'); // 名前付き Cache を取得 or 新規作成
await cache.put(new Request('/app.js'), response); // Request→Response を 1 件保存
const hit = await cache.match('/app.js');          // 照合してヒットすれば Response

重要なのは、保存される Response がボディまで含めた完全なクローンだという点です。put はレスポンスボディの ReadableStream を読み切ってストレージに焼き付けるため、put 後に元の Response 本文を再度読もうとすると失敗します。Fetch API の内部 で見たボディ一度きりの制約がそのまま効くので、レスポンスを「キャッシュにも入れつつアプリでも使う」場合は put の前に clone() しておきます。

キーは Request：照合アルゴリズム

match(request) の核心は、保存済みエントリの中から「同じリクエスト」を見つける照合です。既定の判定軸は次の通りです。

つまり、文字列として渡した URL は内部で Request 化され、URL は Fragment（#...）を除いてフルに比較されます。クエリ文字列も比較対象なので、/api?page=1 で保存したエントリは /api?page=2 の match にはヒットしません。クエリをキャッシュバスティングやトラッキングにしか使っていないなら、{ ignoreSearch: true } でクエリを無視して照合できます。

// /img/logo.png?v=hash で保存していても、バージョン無視で取りたい
const hit = await cache.match('/img/logo.png', { ignoreSearch: true });

method について、Cache Storage は安全な取得である GET（と HEAD）だけをキー対象とし、POST などボディを持つ非冪等メソッドは原則キーにできません。ignoreMethod: true は照合時に method の一致を要求しなくするオプションで、保存時の制約をなくすものではない点に注意します。

Vary：レスポンス側が照合条件を増やす

match がややこしくなる最大の要因が Vary レスポンスヘッダです。サーバーが Vary: Accept-Encoding のように返すと、「このレスポンスは指定ヘッダの値ごとに内容が変わる」という宣言になります。Cache Storage はこれを尊重し、保存時のリクエストの当該ヘッダ値と、match 時のリクエストの当該ヘッダ値が一致しなければヒットさせません。

たとえば Vary: Accept-Language 付きで日本語版を保存した場合、Accept-Language: ja のリクエストでは取れますが、Accept-Language: en のリクエストでは同じ URL でもミスします。これは正しい挙動で、言語が違う内容を誤配信しないための安全装置です。

// Vary を無視して URL+method だけで照合したい
const hit = await cache.match(req, { ignoreVary: true });

// あるいは保存時に Vary を落とした Response を作る（ヘッダは新インスタンスで）
const headers = new Headers(response.headers);
headers.delete('Vary');
const stripped = new Response(response.body, { status: response.status, headers });
await cache.put(req, stripped);

HTTP キャッシュとは完全に独立

最も誤解が多いのが、Cache Storage と HTTP キャッシュ（ブラウザの自動キャッシュ）の関係です。結論から言うと、両者は無関係な別レイヤです。

Cache Storage は put したレスポンスの Cache-Control も Expires も ETag も一切見ません。max-age=60 を付けても 60 秒で消えたりはせず、明示的に delete するまで無期限に残ります。鮮度の概念そのものが Cache API には存在しないので、「古くなったら再取得する」というロジックは Service Worker 側で自分で書く必要があります。これが Service Worker のキャッシュ戦略（cache-first / network-first / stale-while-revalidate など）が必要になる理由です。各戦略の中身は Service Worker のライフサイクルとキャッシュ戦略 に譲りますが、いずれも「Cache Storage は勝手に古くならない」前提に立っています。

一方で、cache.add／addAll や Service Worker 内の fetch がネットワークへ出る瞬間には、ブラウザの HTTP キャッシュが間に挟まり得ます。つまり「Cache Storage に入れるためのフェッチ」が HTTP キャッシュから古い応答を拾ってしまうことがあるため、確実に新鮮な版を焼きたいときは fetch(req, { cache: 'reload' }) で HTTP キャッシュを迂回します。HTTP キャッシュ側の鮮度判定そのものは HTTP キャッシュ の領分です。

部分応答（Range）の扱い

動画や音声、大きな PDF で使われる Range リクエスト（Range: bytes=... → 206 Partial Content）は、Cache API では特に注意が要ります。そもそも**206 レスポンスはそのままでは put できず TypeError になります**（Cache API は仕様上 206 の保存を許しません）。仮に保存できたとしても、match は基本的に「リクエストと保存エントリの対応」で照合するだけで、HTTP キャッシュのようにバイト範囲を自動で切り出して 206 を合成する仕組みは持ちません。したがって Range を扱うメディアでは、フルボディを取得して保存し直す前処理が必要になります。

実務では、Service Worker で fetch を横取りしてキャッシュ済みのフル（200）レスポンスから要求バイト範囲を自前で切り出して 206 を組み立てて返す実装パターンが定番です。Range ヘッダをパースし、ArrayBuffer の該当区間を slice し、Content-Range／Content-Length を付けた 206 を返す、という手順になります。Cache API はあくまでバイト列の保管庫であり、範囲合成はアプリの仕事だと理解しておくと迷いません。

容量管理と退避

Cache Storage は無限ではありません。オリジン単位の共有クォータを、IndexedDB やストレージのトランザクションモデル で扱う IndexedDB・Cache Storage・Service Worker 登録などと同じバジェットから消費します。クォータはオリジンごとに割り当てられ、navigator.storage.estimate() で概算（usage と quota）を取得できます。

const { usage, quota } = await navigator.storage.estimate();
// usage: 現在の使用バイト（概算）, quota: 上限の目安

ディスクの空きが逼迫すると、ブラウザは容量を回収するためにオリジン単位でストレージを丸ごと退避（eviction）します。ここで効くのが永続性（persistence）の区分です。

既定の best-effort ストレージは、空き不足時にブラウザの裁量で退避され得ます。退避は個別エントリ単位ではなくオリジン単位で丸ごと起きるのが要点で、「一部だけ消える」のではなく「そのオリジンの Cache Storage と IndexedDB がまとめて消える」挙動になります。退避順は実装依存ですが、概ね最近使われていないオリジンが先に回収されます（LRU 的）。

これを避けたいオフラインアプリは、navigator.storage.persist() で永続化を要求します。許可されれば persistent 区分になり、空き逼迫でも自動退避の対象外になります（ユーザーが手動で消すか、ブラウザが明示的に許可を取り消した場合のみ消える）。許可されるかはブラウザのヒューリスティック（インストール済み PWA か、エンゲージメントが高いか等）次第で、要求が通らないこともあります。

const persisted = await navigator.storage.persist(); // true なら永続化された
const already = await navigator.storage.persisted();  // 現状の永続状態を確認

バージョニングと一括クリーンアップ

Cache が無期限保持であることの裏返しとして、古いキャッシュの掃除はアプリの責任です。定番は「Cache 名にバージョンを埋め込み、activate 時に旧バージョンを一掃する」パターンです。これにより、デプロイのたびに match が新版を引き、旧版はまとめて解放されます。

const CACHE = 'static-v3';
self.addEventListener('activate', (e) => {
  e.waitUntil((async () => {
    const names = await caches.keys();             // 全 Cache 名
    await Promise.all(
      names.filter((n) => n !== CACHE)             // 現行以外を
           .map((n) => caches.delete(n))           // まとめて削除
    );
  })());
});

まとめ