Dieser Leitfaden konzentriert sich auf funktionsgefährdende Änderungen in Workbox v3 und enthält Beispiele dafür, welche Änderungen Sie bei einem Upgrade von einer Workbox v2-Einrichtung vornehmen müssen.
Wenn Sie derzeit die alte Kombination aus sw-precache
und sw-toolbox
verwenden und zum ersten Mal auf Workbox umstellen möchten, finden Sie hier eine andere Migrationsanleitung.
Hintergrund Version 3
Die Version v3 von Workbox stellt eine erhebliche Refaktorierung der vorhandenen Codebasis dar. Die übergeordneten Ziele sind:
- Minimiere die Größe der Workbox. Die Menge an Service Worker-Laufzeitcode, der heruntergeladen und ausgeführt wird, wurde reduziert. Anstatt ein monolithisches Bundle für alle Nutzer zu aktivieren, wird zur Laufzeit nur Code für die verwendeten Features importiert.
- Workbox hat ein CDN. Wir bieten ein vollständig unterstütztes, Google Cloud Storage-basiertes CDN-Hosting als kanonische Option für den Zugriff auf die Workbox-Laufzeitbibliotheken, was den Einstieg in Workbox erleichtert.
- Bessere Fehlerbehebung und bessere Logs: Die Fehlerbehebung und Protokollierung wurden erheblich verbessert. Fehlerbehebungslogs sind standardmäßig aktiviert, wenn die Workbox von einem
localhost
-Ursprung verwendet wird und alle Logging- und Assertions aus den Produktions-Builds entfernt werden. - Verbessertes Webpack-Plug-in
workbox-webpack-plugin
lässt sich enger in den Webpack-Build-Prozess einbinden. Dies ermöglicht einen Anwendungsfall ohne Konfigurationen, wenn Sie alle Assets in der Build-Pipeline vorab im Cache speichern möchten.
Um diese Ziele zu erreichen und einige Aspekte der vorherigen Benutzeroberfläche zu bereinigen, die sich unangenehm anfühlten oder zu Anti-Patterns führten, mussten in Version 3 einige funktionsgefährdende Änderungen eingeführt werden.
Nicht abwärtskompatible Änderungen
Build-Konfiguration
Die folgenden Änderungen wirken sich auf das Verhalten aller unserer Build-Tools (workbox-build
, workbox-cli
, workbox-webpack-plugin
) aus, die dieselben Konfigurationsoptionen verwenden.
- Der Handler-Name
'fastest'
war zuvor gültig und wurde beim Konfigurieren vonruntimeCaching
als Alias für'staleWhileRevalidate'
behandelt. Sie ist nicht mehr gültig und Entwickler sollten'staleWhileRevalidate'
direkt verwenden. - Mehrere
runtimeCaching.options
-Attributnamen wurden aktualisiert. Außerdem erfolgt eine zusätzliche Parametervalidierung, die dazu führt, dass ein Build bei Verwendung einer ungültigen Konfiguration fehlschlägt. Eine Liste der derzeit unterstützten Optionen finden Sie in der Dokumentation zuruntimeCaching
.
Workbox-Hintergrundsynchronisierung
- Der Konfigurationsparameter
maxRetentionTime
wird jetzt als Anzahl von Minuten und nicht als Anzahl von Millisekunden interpretiert. - Es gibt nun einen erforderlichen String für den Warteschlangennamen, der beim Erstellen der Plug-in- oder der eigenständigen Klasse als erster Parameter übergeben werden muss. Sie wurde zuvor als Eigenschaft der Optionen übergeben. Informationen zur aktualisierten API-Oberfläche finden Sie in der Dokumentation.
workbox-broadcast-cache-update
- Es gibt jetzt einen erforderlichen String für den Kanalnamen, der beim Erstellen der Plug-in- oder der eigenständigen Klasse als erster Parameter übergeben werden muss.
In v2 würden Sie beispielsweise die Plugin-Klasse wie folgt initialisieren:
new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
channelName: 'cache-updates',
headersToCheck: ['etag'],
});
Die entsprechende Verwendung in v3 sieht so aus:
new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});
Informationen zur aktualisierten API-Oberfläche finden Sie in der Dokumentation.
Workbox-Build
- Standardmäßig wird der Musterabgleich
glob
jetzt mit den Optionenfollow: true
(die auf Symlinks folgen) undstrict: true
(die weniger tolerant gegenüber ungewöhnlichen Fehlern ist) durchgeführt. Sie können beide deaktivieren und zum vorherigen Verhalten zurückkehren, indem SieglobFollow: false
und/oderglobStrict: false
in Ihrer Build-Konfiguration festlegen. - Alle Funktionen in
workbox-build
geben in den zurückgegebenen Antworten die zusätzliche Eigenschaftwarnings
zurück. Einige Szenarien, die in Version 2 als schwerwiegende Fehler behandelt wurden, sind jetzt zulässig, werden aber überwarnings
gemeldet, wobei es sich um ein String-Array handelt.
In v2 könnten Sie generateSW
so aufrufen:
const workboxBuild = require('workbox-build');
workboxBuild.generateSW({...})
.then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
.catch((error) => console.error(`Something went wrong: ${error}`));
Sie können zwar denselben Code in Version 3 verwenden, es ist jedoch ratsam, nach warnings
zu suchen und diese zu protokollieren:
const workboxBuild = require('workbox-build');
workboxBuild.generateSW({...})
.then(({count, size, warnings}) => {
for (const warning of warnings) {
console.warn(warning);
}
console.log(`Precached ${count} files, totalling ${size} bytes.`);
})
.catch((error) => console.error(`Something went wrong: ${error}`));
- Entwickler, die ihre eigenen benutzerdefinierten
ManifestTransform
-Funktionen in Version 2 geschrieben haben, müssen das Manifest-Array in einem Objekt zurückgeben. Stattreturn manifestArray;
sollten Sie alsoreturn {manifest: manifestArray};
verwenden.warnings
Wenn Sie eine benutzerdefinierte ManifestTransform
in Version 2 geschrieben haben, verwenden Sie folgenden Code:
const cdnTransform = manifestEntries => {
return manifestEntries.map(entry => {
const cdnOrigin = 'https://example.com';
if (entry.url.startsWith('/assets/')) {
entry.url = cdnOrigin + entry.url;
}
return entry;
});
};
hat ein v3-Äquivalent von:
const cdnTransform = manifestEntries => {
const manifest = manifestEntries.map(entry => {
const cdnOrigin = 'https://example.com';
if (entry.url.startsWith('/assets/')) {
entry.url = cdnOrigin + entry.url;
}
return entry;
});
return {manifest, warnings: []};
};
- Die Funktion
getFileManifestEntries()
wurde ingetManifest()
umbenannt und das zurückgegebene Versprechen enthält jetzt zusätzliche Informationen zu den URLs, die vorab im Cache gespeichert werden.
Code wie den folgenden in v2:
const manifestEntries = await workboxBuild.getFileManifestEntries({...});
kann in Version 3 folgendermaßen umgeschrieben werden:
const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});
// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.
- Die Funktion
generateFileManifest()
wurde entfernt. Entwicklern wird empfohlen, stattdessengetManifest()
aufzurufen und anhand der Antwort Daten im entsprechenden Format auf das Laufwerk zu schreiben.
Workbox-Cache-Ablauf
- Die Plug-in-API ist gleich geblieben. Dies ist der Modus, den die meisten Entwickler letztendlich verwenden werden. Es gibt jedoch erhebliche API-Änderungen, die sich auf Entwickler auswirken, die sie als eigenständige Klasse verwenden. Informationen zur aktualisierten API-Oberfläche finden Sie in der Dokumentation.
workbox-cli
Entwickler können die Befehlszeile mit dem Flag --help
ausführen, um einen vollständigen Satz unterstützter Parameter zu erhalten.
- Der Alias
workbox-cli
für das binäre Script wird nicht mehr unterstützt. Auf die Binärdatei kann jetzt nur alsworkbox
zugegriffen werden. - Die V2-Befehle
generate:sw
undinject:manifest
wurden in Version 3 ingenerateSW
undinjectManifest
umbenannt. - In Version 2 wurde im aktuellen Verzeichnis von
workbox-cli-config.js
als Standardkonfigurationsdatei ausgegangen, wenn keine Datei explizit angegeben wurde. In v3 ist dasworkbox-config.js
.
Zusammengenommen bedeutet dies in v2:
$ workbox inject:manifest
würde den Build-Prozess „Injection-Manifest“ mit einer aus workbox-cli-config.js
gelesenen Konfiguration ausführen. In v3:
$ workbox injectManifest
führt dasselbe aus, liest aber die Konfiguration aus workbox-config.js
.
Workbox-Precaching
- Mit der Methode
precache()
wurden zuvor sowohl die Cache-Änderungen als auch das Routing zur Bereitstellung von im Cache gespeicherten Einträgen eingerichtet. Jetzt ändertprecache()
nur Cache-Einträge und die neue MethodeaddRoute()
wurde eingeführt, um eine Route zu registrieren, um diese im Cache gespeicherten Antworten bereitzustellen. Entwickler, die die vorherige 2-in-1-Funktion nutzen möchten, können zum Aufrufen vonprecacheAndRoute()
wechseln. - Mehrere Optionen, die früher über den
WorkboxSW
-Konstruktor konfiguriert wurden, werden jetzt alsoptions
-Parameter inworkbox.precaching.precacheAndRoute([...], options)
übergeben. Die Standardeinstellungen für diese Optionen sind in der Referenzdokumentation aufgeführt, sofern sie nicht konfiguriert sind. - Standardmäßig werden URLs ohne Dateiendung automatisch auf Übereinstimmung mit einem Cache-Eintrag mit der Erweiterung
.html
geprüft. Wenn beispielsweise eine Anfrage für/path/to/index
gesendet wird, das nicht vorab im Cache gespeichert ist, und es einen vorab im Cache gespeicherten Eintrag für/path/to/index.html
gibt, wird dieser bereits im Cache gespeicherte Eintrag verwendet. Entwickler können dieses neue Verhalten deaktivieren, indem sie{cleanUrls: false}
beim Übergeben von Optionen anworkbox.precaching.precacheAndRoute()
festlegen. workbox-broadcast-update
wird nicht mehr automatisch so konfiguriert, dass Cache-Updates für vorab im Cache gespeicherte Assets angekündigt werden.
Der folgende Code in v2:
const workboxSW = new self.WorkboxSW({
directoryIndex: 'index.html',
ignoreUrlParametersMatching: [/^utm_/],
precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);
hat ein v3-Äquivalent von:
workbox.precaching.addPlugins([
new workbox.broadcastUpdate.Plugin('precache-updates')
]);
workbox.precaching.precacheAndRoute([...], {
cleanUrls: false,
directoryIndex: 'index.html',
ignoreUrlParametersMatching: [/^utm_/],
});
Workbox-Routing
- Entwickler, die
workbox-routing
bisher über denworkbox.router.*
-Namespace eines WorkboxSW-Objekts verwendet haben, müssen zum neuen Namespaceworkbox.routing.*
wechseln. - Routen werden jetzt in der Reihenfolge der ersten registrierten Gewinne ausgewertet. Dies ist die gegenteilige Reihenfolge der
Route
-Bewertung, die in v2 verwendet wurde, wobei die zuletzt registrierteRoute
Vorrang hat. - Die Klasse
ExpressRoute
und die Unterstützung für Platzhalter im Express-Stil wurden entfernt. Dadurch wird die Größe vonworkbox-routing
erheblich reduziert. Strings, die als erster Parameter fürworkbox.routing.registerRoute()
verwendet werden, werden jetzt als genaue Übereinstimmungen behandelt. Platzhalter- oder Teilübereinstimmungen sollten vonRegExp
s verarbeitet werden. Die Verwendung vonRegExp
, die mit einem Teil der Anfrage-URL oder der gesamten Anfrage-URL übereinstimmen, kann eine Route auslösen. - Die Hilfsmethode
addFetchListener()
der KlasseRouter
wurde entfernt. Entwickler können entweder explizit einen eigenenfetch
-Handler hinzufügen oder die vonworkbox.routing
bereitgestellte Schnittstelle verwenden, die implizit einenfetch
-Handler für sie erstellt. - Die Methoden
registerRoutes()
undunregisterRoutes()
wurden entfernt. Die Versionen dieser Methoden, die für eine einzelneRoute
ausgeführt werden, wurden nicht geändert. Entwickler, die mehrere Routen gleichzeitig registrieren oder ihre Registrierung aufheben müssen, sollten stattdessen eine Reihe von Aufrufen anregisterRoute()
oderunregisterRoute()
ausführen.
Der folgende Code in v2:
const workboxSW = new self.WorkboxSW();
workboxSW.router.registerRoute(
'/path/with/.*/wildcard/',
workboxSW.strategies.staleWhileRevalidate()
);
workboxSW.router.registerRoute(
new RegExp('^https://example.com/'),
workboxSW.strategies.networkFirst()
);
hat ein v3-Äquivalent von:
workbox.routing.registerRoute(
new RegExp('^https://example.com/'),
workbox.strategies.networkFirst()
);
workbox.routing.registerRoute(
new RegExp('^/path/with/.*/wildcard'),
workbox.strategies.staleWhileRevalidate()
);
workbox-strategies (früher als workbox-runtime-caching bekannt)
- Das Modul
workbox-runtime-caching
wird jetzt offiziell alsworkbox-strategies
bezeichnet und aufnpm
veröffentlicht unter seinem neuen Namen. - Die Verwendung eines Cache-Ablaufs in einer Strategie ohne die Angabe eines Cache-Namens ist nicht mehr gültig. In Version 2 war dies möglich:
workboxSW.strategies.staleWhileRevalidate({
cacheExpiration: {maxEntries: 50},
});
Dies würde dazu führen, dass Einträge im Standardcache ablaufen, was unerwartet ist. In v3 ist ein Cache-Name erforderlich:
workboxSW.strategies.staleWhileRevalidate({
cacheName: 'my-cache',
plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
- Die Lebenszyklusmethode
cacheWillMatch
wurde incachedResponseWillBeUsed
umbenannt. Für Entwickler sollte dies keine sichtbare Änderung sein, es sei denn, sie haben ihre eigenen Plug-ins entwickelt, die aufcacheWillMatch
reagierten. - Die Syntax zum Angeben von Plug-ins beim Konfigurieren einer Strategie hat sich geändert. Jedes Plug-in muss explizit im Attribut
plugins
der Strategiekonfiguration aufgeführt werden.
Der folgende Code in v2:
const workboxSW = new self.WorkboxSW();
const networkFirstStrategy = workboxSW.strategies.networkFirst({
cacheName: 'my-cache',
networkTimeoutSeconds: 5,
cacheExpiration: {
maxEntries: 50,
},
cacheableResponse: {
statuses: [0, 200],
},
});
hat ein v3-Äquivalent von:
const networkFirstStrategy = workbox.strategies.networkFirst({
cacheName: 'my-cache',
networkTimeoutSeconds: 5,
plugins: [
new workbox.expiration.Plugin({maxEntries: 50}),
new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
],
});
Weitere Informationen finden Sie im Leitfaden Plug-ins verwenden.
workbox-sw
workbox-sw
wurde in eine einfache Ladeschnittstelle umgeschrieben, die einige grundlegende Konfigurationsschritte erfordert und dafür verantwortlich ist, die anderen Module abzurufen, die zur Laufzeit benötigt werden. Anstatt eine neue Instanz derWorkboxSW
-Klasse zu erstellen, interagieren Entwickler mit einer vorhandenen Instanz, die automatisch im globalen Namespace verfügbar gemacht wird.
Bisher in v2:
importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');
const workbox = new WorkboxSW({
skipWaiting: true,
clientsClaim: true,
// etc.
});
workbox.router.registerRoute(...);
In v3 müssen Sie nur das Skript workbox-sw.js
importieren. Eine einsatzbereite Instanz ist dann im globalen Namespace automatisch als workbox
verfügbar:
importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');
// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);
skipWaiting
undclientsClaim
sind keine Optionen mehr, die an den KonstruktorWorkboxSW
übergeben werden. Stattdessen wurden sie in die Methodenworkbox.clientsClaim()
undworkbox.skipWaiting()
geändert.- Die Option
handleFetch
, die zuvor im v2-Konstruktor unterstützt wurde, wird in v3 nicht mehr unterstützt. Entwickler, die ähnliche Funktionen zum Testen ihres Service Workers benötigen, ohne dass Abruf-Handler aufgerufen werden, können die Option Für Netzwerk umgehen in den Entwicklertools von Chrome verwenden.
Workbox-Webpack-Plug-in
Das Plug-in wurde umfassend neu geschrieben und kann in vielen Fällen in einem Modus ohne Konfiguration verwendet werden. Informationen zur aktualisierten API-Oberfläche finden Sie in der Dokumentation.
- Die API stellt jetzt zwei Klassen bereit:
GenerateSW
undInjectManifest
. Dies macht das Wechseln zwischen den Modi explizit gegenüber dem V2-Verhalten, bei dem sich das Verhalten aufgrund des Vorhandenseins vonswSrc
geändert hat. - Standardmäßig werden Assets in der Webpack-Kompilierungspipeline vorab im Cache gespeichert.
globPatterns
muss nicht mehr konfiguriert werden.globPatterns
sollte nur dann weiterhin verwendet werden, wenn du Assets vorab im Cache speichern musst, die nicht in deinem Webpack-Build enthalten sind. Im Allgemeinen sollten Sie bei der Migration zum v3-Plug-in zuerst die gesamte vorherigeglob
-basierte Konfiguration entfernen und nur bei Bedarf wieder hinzufügen.
Unterstützung erhalten
Wir gehen davon aus, dass die meisten Migrationen unkompliziert sein werden. Wenn Probleme auftreten, die in diesem Leitfaden nicht behandelt werden, eröffnen Sie ein Problem auf GitHub.