Cache.match() — Methode · JavaScript-Referenz

Signatur

Cache.prototype.match(request, options)

Beschreibung

Cache.match() sucht in einem bestimmten Cache-Objekt nach einem Eintrag, dessen Anfrage zur übergebenen Anfrage passt. Das zurückgegebene Promise wird mit der zugehörigen Response erfüllt. Gibt es keinen Treffer, wird es mit undefined erfüllt, nicht abgelehnt.

Am häufigsten kommt die Methode in Service Workern zum Einsatz. Dort bildet sie die Grundlage von Offline- und Caching-Strategien wie „Cache First“, „Network First“ oder „Stale-While-Revalidate“. Man kann sie aber auch in normalen Fensterkontexten nutzen, etwa um zu prüfen, ob eine Ressource schon vorab geladen wurde.

Standardmäßig vergleicht die Methode die vollständige URL einschließlich Query-String. Außerdem beachtet sie den Vary-Header der gespeicherten Antwort und berücksichtigt nur GET- und HEAD-Anfragen. Mit dem options-Objekt lässt sich dieses Verhalten lockern. Soll über alle Caches einer Origin gesucht werden, verwendet man stattdessen caches.match() (CacheStorage.match()).

Die Methode ist gleichwertig zu cache.matchAll(request, options), wenn man davon nur den ersten Treffer nimmt. Sie ist aber effizienter, wenn man genau eine Antwort braucht.

Parameter

Name	Typ	Default	Beschreibung
$request Pflicht	Request \| string \| URL		Die gesuchte Anfrage. Das kann ein `Request`-Objekt oder eine URL als String bzw. `URL`-Objekt sein. Relative URLs werden relativ zur Basis-URL des Kontexts aufgelöst.
$options	object	{}	Optionales Objekt, das den Vergleich steuert.
$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. Dann können auch Anfragen mit anderen Methoden als `GET`/`HEAD` einen Treffer liefern.
$options.ignoreVary	boolean	false	Bei `true` wird der `Vary`-Header der gespeicherten Antwort ignoriert. Ein Treffer über die URL genügt dann.

Rückgabewert

Typ

Promise<Response | undefined>

Beschreibung

Ein Promise, das mit der ersten passenden Response erfüllt wird, oder mit undefined, wenn nichts gefunden wurde.

Beispiele

Einfache Abfrage eines Cache-Eintrags

const cache = await caches.open('static-v1');
await cache.add('/styles/main.css');

const response = await cache.match('/styles/main.css');
if (response) {
  console.log('Treffer:', response.status, response.headers.get('content-type'));
} else {
  console.log('Nicht im Cache');
}

Treffer: 200 text/css

Cache-First-Strategie im Service Worker

// sw.js
const CACHE_NAME = 'app-shell-v2';

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

  event.respondWith((async () => {
    const cache = await caches.open(CACHE_NAME);
    const cached = await cache.match(event.request);
    if (cached) return cached; // sofort aus dem Cache liefern

    const networkResponse = await fetch(event.request);
    if (networkResponse.ok) {
      // clone(), weil der Body nur einmal gelesen werden kann
      cache.put(event.request, networkResponse.clone());
    }
    return networkResponse;
  })());
});

Query-String ignorieren (Cache-Busting-Parameter)

const cache = await caches.open('images');
await cache.put('/img/logo.png', new Response('PNG-Daten', {
  headers: { 'Content-Type': 'image/png' }
}));

const strict = await cache.match('/img/logo.png?v=123');
const loose = await cache.match('/img/logo.png?v=123', { ignoreSearch: true });

console.log(strict === undefined);
console.log(loose?.headers.get('Content-Type'));

true image/png

Offline-Fallback bei Netzwerkfehler

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

  event.respondWith((async () => {
    try {
      return await fetch(event.request);
    } catch {
      const cache = await caches.open('offline-v1');
      // Fallback-Seite, die beim install-Event vorab gecacht wurde
      return (await cache.match('/offline.html')) ??
        new Response('Offline', { status: 503 });
    }
  })());
});

// Wichtig · Fallstricke

Kein Treffer führt nicht zu einem Fehler: Das Promise wird mit undefined erfüllt. Prüfen Sie das Ergebnis immer, bevor Sie es an event.respondWith() übergeben. Sonst schlägt die Anfrage mit einem Netzwerkfehler fehl.
Nur ein Lesevorgang pro Body: Eine aus dem Cache gelieferte Response lässt sich nur einmal lesen, etwa per .json() oder .text(). Wird sie mehrfach gebraucht, erzeugen Sie vorher Kopien mit response.clone().
Query-String und Vary: Standardmäßig muss die URL exakt übereinstimmen, und Vary-Header werden berücksichtigt. Verfehlt man einen Treffer unerwartet, liegt das oft an ?v=…-Parametern oder an Vary: Accept-Encoding/Origin.
Methode: POST-Anfragen liefern ohne ignoreMethod: true nie einen Treffer. Speichern lassen sie sich mit put() ohnehin nicht.
Kein automatisches Ablaufen: Die Cache-API beachtet weder Cache-Control noch Expires. Veraltete Einträge müssen Sie selbst mit cache.delete() oder über versionierte Cache-Namen entfernen.
Opake Antworten: Bei Cross-Origin-Anfragen im Modus no-cors gespeicherte Antworten haben status: 0 und sind nicht lesbar.
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt. Sie ist nur in sicheren Kontexten verfügbar (HTTPS oder localhost). Im privaten Modus mancher Browser kann caches fehlen oder eingeschränkt sein.

Siehe auch

Cache Cache.put() Cache.add() Cache.delete() Response