CacheStorage.match() — Methode · JavaScript-Referenz

Signatur

CacheStorage.prototype.match(request, options)

Beschreibung

CacheStorage.match() ist über das globale caches-Objekt erreichbar, im Fenster-Kontext genauso wie in Service Workern. Die Methode sucht einen gespeicherten Eintrag, der zu einer Anfrage passt, und liefert ein Promise. Dieses wird mit der passenden Response erfüllt oder mit undefined, wenn es keinen Treffer gibt.

Ohne weitere Angabe werden alle Caches durchsucht, und zwar in der Reihenfolge, in der sie angelegt wurden (so wie caches.keys() sie liefert). Die erste gefundene Antwort wird zurückgegeben. Mit der Option cacheName lässt sich die Suche auf einen bestimmten Cache begrenzen. Das entspricht dann caches.open(name).then(c => c.match(request)), nur dass kein neuer Cache angelegt wird, falls es den Namen nicht gibt.

Typischer Einsatz ist der fetch-Handler eines Service Workers: Man sucht zuerst im Cache und fragt nur bei einem Fehlschlag das Netzwerk an („Cache first“). Weil es keinen Fehler gibt, wenn nichts gefunden wird, muss man den Rückgabewert immer auf undefined prüfen.

Parameter

Name	Typ	Default	Beschreibung
$request Pflicht	Request\|string\|URL		Die gesuchte Anfrage – als `Request`-Objekt oder als URL. Relative URLs werden gegen die Basis-URL des Skripts aufgelöst.
$options	Object	{}	Optionales Objekt, das die Suche steuert (siehe folgende Einträge).
$options.ignoreSearch	boolean	false	Bei `true` wird der Query-String (`?a=1`) beim Vergleich ignoriert.
$options.ignoreMethod	boolean	false	Bei `true` wird die HTTP-Methode nicht geprüft. Sonst passen nur `GET`- und `HEAD`-Anfragen.
$options.ignoreVary	boolean	false	Bei `true` wird der `Vary`-Header der gespeicherten Antwort beim Vergleich nicht beachtet.
$options.cacheName	string		Name eines bestimmten Caches, in dem gesucht werden soll. Ohne Angabe werden alle Caches durchsucht.

Rückgabewert

Typ

Promise<Response|undefined>

Beschreibung

Ein Promise, das mit der ersten passenden Response erfüllt wird, oder mit undefined, wenn kein Eintrag passt.

Beispiele

Einfache Suche über alle Caches

const response = await caches.match('/styles/main.css');

if (response) {
  console.log('Treffer:', response.status, response.url);
} else {
  console.log('Nicht im Cache');
}

Treffer: 200 https://example.com/styles/main.css

Cache-first-Strategie im Service Worker

// 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 networkResponse = await fetch(event.request);
    const cache = await caches.open('runtime-v1');
    // Klonen, weil ein Body nur einmal gelesen werden kann
    cache.put(event.request, networkResponse.clone());
    return networkResponse;
  })());
});

Gezielt in einem Cache suchen, Query-String ignorieren

const response = await caches.match('/api/produkte?seite=2', {
  cacheName: 'api-v2',
  ignoreSearch: true
});

const daten = response ? await response.json() : [];
console.log(`${daten.length} Produkte aus dem Cache geladen`);

24 Produkte aus dem Cache geladen

Offline-Fallback-Seite ausliefern

self.addEventListener('fetch', (event) => {
  if (event.request.mode !== 'navigate') return;

  event.respondWith(
    fetch(event.request).catch(async () =>
      (await caches.match('/offline.html', { cacheName: 'static-v1' })) ??
      new Response('Offline', { status: 503 })
    )
  );
});

// Wichtig · Fallstricke

Kein Fehler bei Fehlschlag: Gibt es keinen Treffer, wird das Promise mit undefined erfüllt und nicht abgelehnt. Prüfe den Wert deshalb immer, bevor du ihn an respondWith() weitergibst. Sonst entsteht ein Netzwerkfehler.
Sicherer Kontext: caches gibt es nur über HTTPS (oder auf localhost). In manchen privaten Browserfenstern ist es eingeschränkt oder wirft einen SecurityError.
Reihenfolge: Liegt dieselbe URL in mehreren Caches, gewinnt der zuerst angelegte Cache. Beim Versionieren (z. B. v1 → v2) sollte man alte Caches im activate-Event löschen oder mit cacheName gezielt suchen.
Nur GET/HEAD: Ohne ignoreMethod: true passen POST-Anfragen nie.
Vary-Header: Antworten mit Vary (z. B. Vary: Accept-Encoding) passen nur, wenn die genannten Anfrage-Header übereinstimmen. Mit ignoreVary lässt sich das umgehen.
Performance: Eine Suche über alle Caches kann bei vielen Caches langsamer sein. Mit cacheName bleibt die Suche gezielt.
Undurchsichtige Antworten (type: 'opaque', von Cross-Origin-Anfragen im Modus no-cors) werden zwar gefunden, aber ihren Status und Inhalt kann man nicht auslesen.

Siehe auch

CacheStorage CacheStorage.open() CacheStorage.has() CacheStorage.keys() CacheStorage.delete() Cache.match() Cache.put() FetchEvent.respondWith()