ServiceWorkerRegistration.unregister() — Methode · JavaScript-Referenz

Signatur

ServiceWorkerRegistration.prototype.unregister()

Beschreibung

Mit unregister() entfernen Sie eine Service-Worker-Registrierung. Das zurückgegebene Promise wird mit true erfüllt, wenn eine Registrierung gefunden und zur Aufhebung markiert wurde. Wird keine passende Registrierung gefunden, ist der Wert false. Tritt ein Fehler auf, wird das Promise abgelehnt.

Die Aufhebung wirkt nicht sofort: Seiten, die gerade vom Service Worker gesteuert werden, bleiben bis zum Neuladen oder Schließen unter seiner Kontrolle. Erst wenn kein Client mehr die Registrierung nutzt, wird sie tatsächlich entfernt. Deshalb ist navigator.serviceWorker.controller direkt nach dem Aufruf oft noch gesetzt.

Typische Anwendungsfälle:

ein fehlerhaft ausgelieferter Service Worker soll entfernt werden („Kill-Switch“),
ein Offline-Modus soll per Einstellung abschaltbar sein,
in der Entwicklung sollen alte Worker aufgeräumt werden,
eine Anwendung wird auf eine andere Architektur umgestellt, die ohne Service Worker auskommt.

Beachten Sie: unregister() löscht keine Einträge in der Cache Storage API. Zwischengespeicherte Antworten, die der Worker angelegt hat, müssen Sie gesondert mit caches.delete() entfernen.

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Wird mit true erfüllt, wenn die Registrierung zur Aufhebung markiert wurde, sonst mit false. Tritt ein Fehler auf, wird das Promise abgelehnt.

Beispiele

Aktuelle Registrierung aufheben

const removeServiceWorker = async () => {
  if (!('serviceWorker' in navigator)) return;

  const registration = await navigator.serviceWorker.getRegistration();
  if (!registration) {
    console.log('Keine Registrierung vorhanden');
    return;
  }

  const success = await registration.unregister();
  console.log(success ? 'Service Worker entfernt' : 'Aufhebung fehlgeschlagen');
};

removeServiceWorker();

Service Worker entfernt

Alle Registrierungen und Caches entfernen (Kill-Switch)

const resetOfflineSupport = async () => {
  const registrations = await navigator.serviceWorker.getRegistrations();
  const results = await Promise.all(registrations.map((reg) => reg.unregister()));

  // Caches werden von unregister() NICHT gelöscht
  const cacheNames = await caches.keys();
  await Promise.all(cacheNames.map((name) => caches.delete(name)));

  console.log(`${results.filter(Boolean).length} Worker entfernt, ${cacheNames.length} Caches gelöscht`);

  // Neu laden, damit die Seite nicht mehr vom alten Worker gesteuert wird
  if (navigator.serviceWorker.controller) {
    location.reload();
  }
};

resetOfflineSupport();

2 Worker entfernt, 3 Caches gelöscht

Offline-Modus per Schalter deaktivieren

const toggle = document.querySelector('#offline-toggle');

toggle.addEventListener('change', async (event) => {
  if (event.target.checked) {
    await navigator.serviceWorker.register('/sw.js', { scope: '/' });
    console.log('Offline-Modus aktiviert');
    return;
  }

  const registration = await navigator.serviceWorker.getRegistration('/');
  try {
    const ok = await registration?.unregister();
    console.log(ok ? 'Offline-Modus deaktiviert' : 'Nichts zu deaktivieren');
  } catch (error) {
    console.error('Fehler beim Aufheben:', error);
  }
});

Offline-Modus deaktiviert

// Wichtig · Fallstricke

Die Aufhebung wirkt verzögert: Bereits gesteuerte Seiten bleiben unter der Kontrolle des Workers, bis sie neu geladen oder geschlossen werden. Wenn der Worker sofort keine Wirkung mehr haben soll, laden Sie die Seite nach dem Aufruf neu.
Caches bleiben erhalten: Daten in Cache Storage, IndexedDB usw. werden nicht gelöscht. Entfernen Sie diese bei Bedarf selbst mit caches.delete().
Push-Abonnements: Mit der Aufhebung verfallen zugehörige Push-Abonnements. Informieren Sie gegebenenfalls Ihren Server, damit er keine Nachrichten mehr an veraltete Endpunkte sendet.
Ein erneuter Aufruf von register() vor dem endgültigen Entfernen kann die markierte Registrierung wiederbeleben.
Service Worker gibt es nur in sicheren Kontexten (HTTPS oder localhost). Prüfen Sie vorher mit 'serviceWorker' in navigator, ob die API verfügbar ist. Im privaten Modus von Firefox steht die API nicht zur Verfügung.
Als serverseitigen Kill-Switch können Sie auch den Header Clear-Site-Data: "storage" senden. Er entfernt Registrierungen und Caches auf einmal.

Siehe auch

ServiceWorkerRegistration.update() ServiceWorkerRegistration.getNotifications() ServiceWorkerRegistration.showNotification() ServiceWorkerContainer.register() ServiceWorker.postMessage()