In diesem Leitfaden geht es hauptsächlich um die in Workbox v4 eingeführten Änderungen, einschließlich Beispielen für Änderungen, die Sie beim Upgrade von Workbox v3 vornehmen müssen.
Wichtige Änderungen
workbox-precaching
Die Namenskonvention für vorab im Cache gespeicherte Einträge wurde aktualisiert. Bei Einträgen, deren URLs Informationen zur Versionierung benötigen (d.h. Einträge, die im Pre-Cache-Manifest ein revision-Feld enthalten), werden 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 mithilfe von IndexedDB getrennt von den Cacheschlü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. Beim Upgrade auf Workbox v4 werden die im Cache Ihrer Nutzer gespeicherten Assets automatisch in das neue Cache-Schlüsselformat migriert. Künftig werden die vorab im Cache gespeicherten Ressourcen auf dieselbe Weise wie zuvor bereitgestellt.
Cache-Schlüssel direkt verwenden
Einige Entwickler müssen möglicherweise direkt auf Pre-Cache-Einträge zugreifen, außerhalb des Kontexts von workbox.precaching.precacheAndRoute(). Sie können beispielsweise ein Bild vorab im Cache speichern, das Sie dann als Fallback-Antwort verwenden, wenn ein Bild nicht aus dem Netzwerk abgerufen werden kann.
Wenn Sie auf diese Weise vorab im Cache gespeicherte Assets verwenden, müssen Sie ab Workbox v4 einen zusätzlichen Schritt ausführen, um eine ursprüngliche URL in den entsprechenden Cache-Schlüssel umzuwandeln, mit dem der im Cache gespeicherte Eintrag gelesen werden kann. Rufen Sie dazu workbox.precaching.getCacheKeyForURL(originURL) auf.
Wenn Sie beispielsweise wissen, dass 'fallback.png' vorab im Cache gespeichert ist:
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 zwischengespeicherte Daten bereinigen
Aufgrund der Änderungen am Precaching in Workbox v4 sind ältere Precaches, die mit früheren Versionen von Workbox erstellt wurden, nicht kompatibel. Standardmäßig bleiben sie unverändert. Wenn Sie von Workbox 3 auf Workbox 4 umstellen, haben Sie zwei Kopien aller Ihrer vorab im Cache gespeicherten Ressourcen.
Sie können dies vermeiden, indem Sie einen Aufruf von workbox.precaching.cleanupOutdatedCaches() direkt in einen Service Worker einfügen oder die neue Option cleanupOutdatedCaches: true festlegen, wenn Sie ein Build-Tool im GenerateSW-Modus verwenden. Da die Logik der Cache-Bereinigung zur Suche nach älteren Pre-Caches anhand der Cache-Namenskonventionen arbeitet und Entwickler die Möglichkeit haben, diese Konventionen zu überschreiben, sind wir auf Sicherheit geachtet und haben diese nicht standardmäßig aktiviert.
Wenn Entwickler Probleme mit der Funktion feststellen, z. B. fälschlicherweise gelöschte Inhalte, sollten sie uns dies mitteilen.
Groß- und Kleinschreibung von Parametern
Zwei optionale Parameter, die an workbox.precaching.precacheAndRoute() und workbox.precaching.addRoute() übergeben werden können, wurden umbenannt, um unsere Groß- und Kleinschreibung zu standardisieren. ignoreUrlParametersMatching ist jetzt ignoreURLParametersMatching und cleanUrls ist jetzt cleanURLs.
workbox-strategies
Es gibt zwei ungefähr gleichwertige Möglichkeiten, in workbox-strategies eine Instanz eines Handlers zu erstellen. Die Factory-Methode wird eingestellt. Stattdessen wird der Konstruktor der Strategie explizit aufgerufen.
// 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 Syntax der Fabrikmethode funktioniert zwar weiterhin in Version 4, bei Verwendung wird jedoch eine Warnung protokolliert. Wir empfehlen Entwicklern, vor der Entfernung der Unterstützung in der zukünftigen Version 5 zu migrieren.
workbox-background-sync
Die workbox.backgroundSync.Queue-Klasse wurde neu geschrieben, um Entwicklern mehr Flexibilität und Kontrolle darüber zu bieten, wie Anfragen der Warteschlange hinzugefügt und wiedergegeben werden.
In Version 3 gab es mit der Klasse Queue nur eine Möglichkeit, Anfragen zur Warteschlange hinzuzufügen (Methode addRequest()), es gab 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 hinzugefügt:
pushRequest()popRequest()shiftRequest()unshiftRequest()
In Version 3 akzeptierte die Queue-Klasse auch mehrere Callbacks, mit denen Sie beobachten konnten, wann Anfragen wiederholt wurden (requestWillEnqueue, requestWillReplay, queueDidReplay). Die meisten Entwickler wollten jedoch nicht nur Beobachtung, sondern auch steuern, wie die Warteschlange wiedergegeben wird, einschließlich der Möglichkeit, einzelne Anfragen dynamisch zu ändern, neu anzuordnen oder sogar abzubrechen.
In Version 4 wurden diese Callbacks durch einen einzelnen onSync-Callback entfernt. Dieser wird jedes Mal aufgerufen, wenn der Browser eine erneute Wiedergabe ausführt. Standardmäßig ruft der onSync-Callback replayRequests() auf. Wenn du jedoch mehr Kontrolle über den Wiedergabevorgang haben möchtest, kannst du die oben aufgeführten arrayähnlichen Methoden verwenden, um die Warteschlange nach Belieben wiederzugeben.
Hier ein Beispiel für eine benutzerdefinierte Wiedergabelogik:
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!');
},
});
Ebenso akzeptiert die Klasse workbox.backgroundSync.Plugin dieselben Argumente wie die Klasse Queue, da intern eine Queue-Instanz erstellt wird. Sie wurde daher auf die gleiche Weise geändert.
Workbox-Ablauf
Das npm-Paket wurde in workbox-expiration umbenannt, um der Namenskonvention für andere Module zu entsprechen. Funktional gesehen entspricht dieses Paket dem älteren workbox-cache-expiration-Paket, das mittlerweile eingestellt wurde.
Workbox-Broadcast-Update
Das npm-Paket wurde in workbox-broadcast-update umbenannt, um der Namenskonvention für andere Module zu entsprechen. Funktional gesehen entspricht dieses Paket dem älteren workbox-broadcast-cache-update-Paket, das mittlerweile eingestellt wurde.
workbox-core
In Workbox v3 konnte die Detaillierung der Protokollebenen über die Methode workbox.core.setLogLevel() gesteuert werden, bei der einer der Werte im workbox.core.LOG_LEVELS-Enum übergeben wurde. Sie können den aktuellen Loglevel auch über workbox.core.logLevel abrufen.
In Workbox v4 wurden sie alle entfernt, da alle modernen Entwicklertools jetzt umfangreiche Protokollfilterfunktionen bieten (siehe Konsolenausgabe filtern für die Chrome-Entwicklertools).
workbox-sw
Zwei Methoden, die zuvor direkt im Namespace workbox (entspricht dem Modul workbox-sw) freigegeben wurden, wurden stattdessen in workbox.core verschoben. workbox.skipWaiting() wurde zu workbox.core.skipWaiting() und workbox.clientsClaim() zu workbox.core.clientsClaim().
Build-Tool-Konfiguration
Die Benennung einiger Optionen, die an „workbox-cli“, „workbox-build“ oder „workbox-webpack-plugin“ übergeben werden können, hat sich geändert. Die Verwendung von „Url“ in einem Optionsnamen wurde eingestellt und durch „URL“ ersetzt. Daher sind die folgenden Optionennamen vorzuziehen:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
Die Variante „Url“ dieser Optionen funktioniert in Version 4 zwar weiterhin, führt aber zu einer Warnmeldung. Wir empfehlen Entwicklern, vor der Veröffentlichung von Version 5 zu migrieren.
Neue Funktionen
workbox-window
Das neue workbox-window-Modul vereinfacht die Registrierung von Service Workern und das Erkennen von Updates. Außerdem bietet es eine Standardkommunikationsmethode 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 optional. Wir hoffen aber, dass Entwickler es nützlich finden und einige ihrer handgeschriebenen Logikprogramme migrieren, um sie bei Bedarf zu verwenden. Weitere Informationen zur Verwendung von workbox-window finden Sie im Modulleitfaden.
Beispiel für eine Migration
Ein Beispiel für eine reale Migration von Workbox v3 zu v4 finden Sie in dieser Pull-Anfrage.
Hilfe erhalten
Wir gehen davon aus, dass die meisten Migrationen unkompliziert ablaufen. Wenn Probleme auftreten, die in diesem Leitfaden nicht behandelt werden, erstelle bitte einen Issue auf GitHub.