Dieser Leitfaden konzentriert sich auf funktionsgefährdende Änderungen in Workbox v4 und enthält Beispiele dafür, welche Änderungen Sie bei einem Upgrade von Workbox v3 vornehmen müssen.
Nicht abwärtskompatible Änderungen
Workbox-Precaching
Die Namenskonvention für vorab im Cache gespeicherte Einträge wurde aktualisiert. Jetzt werden für Einträge, deren URLs Überarbeitungsinformationen benötigen (d.h. Einträge, die im Precache-Manifest ein revision-Feld enthalten), diese Versionsinformationen als Teil des Cache-Schlüssels in einem speziellen __WB_REVISION__-URL-Suchparameter gespeichert, der an die ursprüngliche URL angehängt wird. Bisher wurden diese Informationen mit IndexedDB getrennt von den Cache-Schlüsseln gespeichert.
Entwickler, die das Precaching über workbox.precaching.precacheAndRoute() nutzen, was der häufigste Anwendungsfall ist, müssen keine Änderungen an ihrer Service Worker-Konfiguration vornehmen. Nach dem Upgrade auf Workbox v4 werden die im Cache gespeicherten Assets Ihrer Nutzer automatisch zum neuen Cache-Schlüsselformat migriert. Die im Cache gespeicherten Ressourcen werden dann weiterhin wie zuvor bereitgestellt.
Cache-Schlüssel direkt verwenden
Einige Entwickler müssen möglicherweise direkt außerhalb des Kontexts von workbox.precaching.precacheAndRoute() auf Precache-Einträge zugreifen. Sie können beispielsweise ein Bild vorab im Cache speichern, das dann als Fallback-Antwort verwendet wird, wenn ein Bild nicht aus dem Netzwerk abgerufen werden kann.
Wenn Sie vorab im Cache gespeicherte Assets auf diese Weise verwenden, müssen Sie ab Workbox Version 4 einen zusätzlichen Schritt ausführen, um eine Original-URL in den entsprechenden Cache-Schlüssel zu übersetzen, der zum Lesen des im Cache gespeicherten Eintrags verwendet werden kann. Dazu rufen Sie workbox.precaching.getCacheKeyForURL(originURL) auf.
Wenn Sie beispielsweise wissen, dass 'fallback.png' vorab im Cache gespeichert wird:
const imageFallbackCacheKey =
workbox.precaching.getCacheKeyForURL('fallback.png');
workbox.routing.setCatchHandler(({event}) => {
switch (event.request.destination) {
case 'image':
return caches.match(imageFallbackCacheKey);
break;
// ...other fallback logic goes here...
}
});
Alte vorab im Cache gespeicherte Daten bereinigen
Aufgrund der Änderungen beim Precaching in Workbox v4 sind ältere Precaches, die aus früheren Versionen von Workbox erstellt wurden, nicht kompatibel. Standardmäßig bleiben sie unverändert. Wenn Sie ein Upgrade von Workbox v3 auf Workbox v4 durchführen, erhalten Sie zwei Kopien all Ihrer vorab im Cache gespeicherten Ressourcen.
Um dies zu vermeiden, können Sie einem Service Worker direkt Aufrufe von workbox.precaching.cleanupOutdatedCaches() hinzufügen oder die neue cleanupOutdatedCaches: true-Option festlegen, wenn Sie ein Build-Tool im GenerateSW-Modus verwenden. Da die Cache-Bereinigungslogik auf Cache-Namenskonventionen agiert, um ältere Precaches zu finden, und da Entwickler diese Konventionen überschreiben können, haben wir auf der Seite der Sicherheit einen Fehler gemacht und dies nicht standardmäßig aktiviert.
Entwickler, die bei der Nutzung dieser Funktion auf Probleme stoßen (z. B. falsch-positive Behauptungen im Hinblick auf das Löschen), informieren wir uns bitte darüber.
Großschreibung der Parameter
Zwei optionale Parameter, die an workbox.precaching.precacheAndRoute() und workbox.precaching.addRoute() übergeben werden können, wurden umbenannt, um unsere allgemeine Großschreibungskonvention zu standardisieren. ignoreUrlParametersMatching ist jetzt ignoreURLParametersMatching und cleanUrls ist jetzt cleanURLs.
Workbox-Strategien
Es gibt zwei ungefähr gleichwertige Methoden zum Erstellen einer Handler-Instanz in workbox-strategies. Die Factory-Methode wird verworfen, da der Konstruktor der Strategie explizit aufgerufen wird.
// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});
// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});
Die Factory-Methode funktioniert zwar in v4 weiterhin, bei Verwendung dieser Methode wird jedoch eine Warnung protokolliert. Wir empfehlen Entwicklern, die Migration vorzunehmen, bevor die Unterstützung in der zukünftigen v5-Version eingestellt wird.
Workbox-Hintergrundsynchronisierung
Die workbox.backgroundSync.Queue-Klasse wurde umgeschrieben, um Entwicklern mehr Flexibilität und Kontrolle darüber zu bieten, wie Anfragen zur Warteschlange hinzugefügt und wiedergegeben werden.
In v3 gab es nur eine Möglichkeit für die Queue-Klasse, Anfragen zur Warteschlange hinzuzufügen (die Methode addRequest()). Sie hatte jedoch keine Möglichkeit, die Warteschlange zu ändern oder Anfragen zu entfernen.
In Version 4 wurde die Methode addRequests() entfernt und die folgenden Array-ähnlichen Methoden wurden hinzugefügt:
pushRequest()popRequest()shiftRequest()unshiftRequest()
In Version 3 akzeptierte die Klasse Queue auch mehrere Callbacks, mit denen Sie beobachten konnten, wann Anfragen wiederholt werden (requestWillEnqueue, requestWillReplay, queueDidReplay). Die meisten Entwickler stellten jedoch fest, dass sie nicht nur die Wiedergabe der Warteschlange steuern wollten, sondern auch die Möglichkeit, einzelne Anfragen dynamisch zu ändern, neu anzuordnen oder sogar abzubrechen.
In Version 4 wurden diese Callbacks zugunsten eines einzelnen onSync-Callbacks entfernt, der bei jedem Wiederholungsversuch im Browser ausgelöst wird. Standardmäßig ruft der onSync-Callback replayRequests() auf. Wenn Sie jedoch mehr Kontrolle über die Wiederholung benötigen, können Sie die oben aufgeführten Array-ähnlichen Methoden verwenden, um die Warteschlange beliebig wiederzugeben.
Hier ein Beispiel für eine benutzerdefinierte Wiederholungslogik:
const queue = new workbox.backgroundSync.Queue('my-queue-name', {
onSync: async ({queue}) => {
let entry;
while ((entry = await this.shiftRequest())) {
try {
await fetch(entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
await this.unshiftRequest(entry);
return;
}
}
console.log('Replay complete!');
},
});
Auf ähnliche Weise akzeptiert die Klasse workbox.backgroundSync.Plugin die gleichen Argumente wie die Klasse Queue (da sie intern eine Queue-Instanz erstellt) und daher auf die gleiche Weise geändert wurde.
Workbox-Ablauf
Das Paket npm wurde in workbox-expiration umbenannt, entsprechend der Namenskonvention anderer Module. Die Funktionsweise dieses Pakets entspricht dem älteren workbox-cache-expiration-Paket, das mittlerweile eingestellt wurde.
Workbox-Broadcast-Update
Das Paket npm wurde in workbox-broadcast-update umbenannt, entsprechend der Namenskonvention anderer Module. Die Funktionsweise dieses Pakets entspricht dem älteren workbox-broadcast-cache-update-Paket, das mittlerweile eingestellt wurde.
Workbox Core
In Workbox v3 konnte die Ausführlichkeit der Logebenen über die Methode workbox.core.setLogLevel() gesteuert werden, für die Sie einen der Werte in der Aufzählung workbox.core.LOG_LEVELS übergeben. Sie können die aktuelle Logebene auch über workbox.core.logLevel auslesen.
In Workbox v4 wurden all diese Funktionen entfernt, da alle modernen Entwicklertools jetzt mit umfassenden Filterfunktionen für Protokolle ausgestattet sind. Weitere Informationen zu Chrome-Entwicklertools finden Sie unter Konsolenausgabe filtern.
Workbox-Sw
Zwei Methoden, die zuvor direkt im Namespace workbox bereitgestellt wurden (der dem Modul workbox-sw entspricht) wurden stattdessen zu workbox.core verschoben. workbox.skipWaiting() ist zu workbox.core.skipWaiting() geworden und workbox.clientsClaim() ist zu workbox.core.clientsClaim() geworden.
Konfiguration des Build-Tools
Die Benennung einiger Optionen, die an „workbox-cli“, „workbox-build“ oder „workbox-webpack-plugin“ übergeben werden können, hat sich geändert. Wann immer "URL" in einem Optionsnamen verwendet wurde, wurde dies zugunsten von "URL" eingestellt. Daher werden die folgenden Optionsnamen bevorzugt:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
Die URL-Variante dieser Optionsnamen funktioniert in Version 4 zwar weiterhin, wird jedoch in einer Warnmeldung angezeigt. Wir empfehlen Entwicklern, vor Version 5 zu migrieren.
Neue Funktionen
Arbeitsbereich-Fenster
Das neue Modul workbox-window vereinfacht die Service Worker-Registrierung und die Erkennung von Updates und bietet eine Standardmethode für die Kommunikation zwischen Code, der im Service Worker ausgeführt wird, und Code, der im window-Kontext Ihrer Webanwendung ausgeführt wird.
Die Verwendung von workbox-window ist zwar optional, aber wir hoffen, dass die Entwickler die App als nützlich empfinden und gegebenenfalls einen Teil der handschriftlichen Logik zur Verwendung migrieren. Weitere Informationen zur Verwendung von workbox-window finden Sie im Leitfaden für das Modul.
Beispielmigration
Ein Beispiel für eine Migration aus der Praxis von Workbox v3 zu v4 finden Sie in dieser Pull-Anfrage.
Unterstützung erhalten
Wir gehen davon aus, dass die meisten Migrationen unkompliziert sein werden. Wenn Probleme auftreten, die nicht in diesem Leitfaden beschrieben sind, erheben Sie ein Problem in GitHub.