Diese Seite wurde von der Cloud Translation API übersetzt.

Von Workbox v2 zu v3 migrieren

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 von runtimeCaching 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 zu runtimeCaching.

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 Optionen follow: true (die auf Symlinks folgen) und strict: true (die weniger tolerant gegenüber ungewöhnlichen Fehlern ist) durchgeführt. Sie können beide deaktivieren und zum vorherigen Verhalten zurückkehren, indem Sie globFollow: false und/oder globStrict: false in Ihrer Build-Konfiguration festlegen.
Alle Funktionen in workbox-build geben in den zurückgegebenen Antworten die zusätzliche Eigenschaft warnings zurück. Einige Szenarien, die in Version 2 als schwerwiegende Fehler behandelt wurden, sind jetzt zulässig, werden aber über warnings 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. Statt return manifestArray; sollten Sie also return {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 in getManifest() 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, stattdessen getManifest() 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 als workbox zugegriffen werden.
Die V2-Befehle generate:sw und inject:manifest wurden in Version 3 in generateSW und injectManifest 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 das workbox-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 ändert precache() nur Cache-Einträge und die neue Methode addRoute() 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 von precacheAndRoute() wechseln.
Mehrere Optionen, die früher über den WorkboxSW-Konstruktor konfiguriert wurden, werden jetzt als options-Parameter in workbox.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 an workbox.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 den workbox.router.*-Namespace eines WorkboxSW-Objekts verwendet haben, müssen zum neuen Namespace workbox.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 registrierte Route Vorrang hat.
Die Klasse ExpressRoute und die Unterstützung für Platzhalter im Express-Stil wurden entfernt. Dadurch wird die Größe von workbox-routing erheblich reduziert. Strings, die als erster Parameter für workbox.routing.registerRoute() verwendet werden, werden jetzt als genaue Übereinstimmungen behandelt. Platzhalter- oder Teilübereinstimmungen sollten von RegExps verarbeitet werden. Die Verwendung von RegExp, die mit einem Teil der Anfrage-URL oder der gesamten Anfrage-URL übereinstimmen, kann eine Route auslösen.
Die Hilfsmethode addFetchListener() der Klasse Router wurde entfernt. Entwickler können entweder explizit einen eigenen fetch-Handler hinzufügen oder die von workbox.routing bereitgestellte Schnittstelle verwenden, die implizit einen fetch-Handler für sie erstellt.
Die Methoden registerRoutes() und unregisterRoutes() wurden entfernt. Die Versionen dieser Methoden, die für eine einzelne Route 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 an registerRoute() oder unregisterRoute() 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 als workbox-strategies bezeichnet und auf npm 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 in cachedResponseWillBeUsed umbenannt. Für Entwickler sollte dies keine sichtbare Änderung sein, es sei denn, sie haben ihre eigenen Plug-ins entwickelt, die auf cacheWillMatch 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 der WorkboxSW-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 und clientsClaim sind keine Optionen mehr, die an den Konstruktor WorkboxSW übergeben werden. Stattdessen wurden sie in die Methoden workbox.clientsClaim() und workbox.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.

Die Option „Für Netzwerk umgehen“ in den Chrome-Entwicklertools.

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 und InjectManifest. Dies macht das Wechseln zwischen den Modi explizit gegenüber dem V2-Verhalten, bei dem sich das Verhalten aufgrund des Vorhandenseins von swSrc 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 vorherige glob-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.