CacheStorage — Schnittstelle · JavaScript-Referenz

Signatur

interface CacheStorage

Beschreibung

CacheStorage ist der zentrale Speicher für alle benannten Cache-Objekte eines Ursprungs (Origin). Man erzeugt die Schnittstelle nicht selbst, sondern greift über die globale Eigenschaft caches (window.caches bzw. self.caches in Workern) auf sie zu. Jeder Cache speichert Paare aus Request und Response und bleibt erhalten, bis er ausdrücklich gelöscht wird oder der Browser den Speicher räumt.

Typischer Einsatzort ist der Service Worker: Beim install-Ereignis werden statische Ressourcen vorab in einen versionierten Cache gelegt, beim activate-Ereignis veraltete Caches entfernt und beim fetch-Ereignis Anfragen aus dem Cache beantwortet. So entstehen offline-fähige Web-Apps (PWAs). Die API steht aber auch im normalen Fensterkontext zur Verfügung.

Alle Methoden arbeiten asynchron und geben ein Promise zurück:

open(cacheName) – öffnet einen Cache bzw. legt ihn an und liefert ein Promise<Cache>.
has(cacheName) – prüft, ob ein Cache mit diesem Namen existiert (Promise<boolean>).
delete(cacheName) – löscht einen Cache (Promise<boolean>).
keys() – liefert die Namen aller Caches in Erstellungsreihenfolge (Promise<string[]>).
match(request, options) – durchsucht alle Caches (oder mit options.cacheName nur einen) nach einer passenden Antwort (Promise<Response | undefined>).

Parameter

Name	Typ	Default	Beschreibung
$cacheName Pflicht	string		Name des Caches bei `open()`, `has()` und `delete()`. Am besten mit Version, z. B. `"static-v2"`.
$request Pflicht	Request \| string \| URL		Anfrage bzw. URL, nach der `match()` in allen Caches sucht.
$options	{ ignoreSearch?: boolean, ignoreMethod?: boolean, ignoreVary?: boolean, cacheName?: string }	{}	Optionen für `match()`: Query-String ignorieren, HTTP-Methode ignorieren, `Vary`-Header ignorieren oder die Suche auf einen bestimmten Cache einschränken.

Rückgabewert

Typ

CacheStorage

Beschreibung

Über caches erhält man die CacheStorage-Instanz des aktuellen Ursprungs; ihre Methoden liefern jeweils ein Promise (siehe Beschreibung).

Beispiele

Statische Ressourcen im Service Worker vorab cachen

// sw.js
const CACHE_NAME = 'static-v2';
const ASSETS = ['/', '/index.html', '/styles.css', '/app.js'];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(ASSETS))
  );
});

Veraltete Caches beim Aktivieren entfernen

// sw.js
const CURRENT = ['static-v2'];

self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    const names = await caches.keys();
    await Promise.all(
      names
        .filter((name) => !CURRENT.includes(name))
        .map((name) => caches.delete(name))
    );
  })());
});

Cache-first-Strategie mit Netzwerk-Fallback

// sw.js
self.addEventListener('fetch', (event) => {
  if (event.request.method !== 'GET') return;

  event.respondWith((async () => {
    const cached = await caches.match(event.request);
    if (cached) return cached;

    const response = await fetch(event.request);
    const cache = await caches.open('runtime-v1');
    // Response-Body ist nur einmal lesbar – daher klonen
    cache.put(event.request, response.clone());
    return response;
  })());
});

Caches im Fensterkontext prüfen und auflisten

if ('caches' in window) {
  const exists = await caches.has('static-v2');
  console.log('static-v2 vorhanden:', exists);
  console.log('Alle Caches:', await caches.keys());
}

static-v2 vorhanden: true Alle Caches: ["static-v2", "runtime-v1"]

// Wichtig · Fallstricke

Nur in sicheren Kontexten: caches gibt es nur über HTTPS (oder localhost). In unsicheren Kontexten ist die Eigenschaft undefined, in manchen Browsern wirft der Zugriff einen SecurityError. Vorher mit 'caches' in self prüfen.
Kein automatisches Ablaufen: Der Cache beachtet HTTP-Caching-Header wie Cache-Control nicht. Einträge bleiben, bis man sie selbst löscht. Deshalb Cache-Namen versionieren und alte Caches im activate-Handler aufräumen.
Speicherkontingent: Der Browser kann bei Speichermangel alle Daten eines Ursprungs löschen. Mit navigator.storage.estimate() und navigator.storage.persist() lassen sich Kontingent abfragen und dauerhafte Speicherung anfordern. Safari räumt Skript-Speicher nach längerer Inaktivität auf.
Opake Antworten: Cross-Origin-Antworten ohne CORS (type: \"opaque\") können gecacht werden, belegen aber oft deutlich mehr Kontingent (Auffüllung) und haben den Status 0 – Fehler sind so nicht erkennbar.
caches.match() durchsucht die Caches in Erstellungsreihenfolge und liefert den ersten Treffer. Kein Treffer ergibt undefined, kein Fehler.
Im privaten Modus einiger Browser (z. B. älteres Firefox) ist die API gesperrt oder nur flüchtig verfügbar.

Siehe auch

Cache caches Request Response SharedStorage