Von Workbox v2 zu v3 migrieren

Dieser Leitfaden konzentriert sich auf funktionsgefährdende Änderungen, die in Workbox v3 eingeführt wurden. Es enthält Beispiele dafür, welche Änderungen Sie vornehmen müssen, wenn Sie ein Upgrade von einer Workbox v2-Einrichtung ausführen.

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.

v3-Hintergrund

Die Workbox v3-Version stellt eine erhebliche Refaktorierung der vorhandenen Codebasis dar. Die übergeordneten Ziele sind:

  • Minimieren Sie die Größe der Workbox. Die Menge an Service Worker-Laufzeitcode, der heruntergeladen und ausgeführt wird, wurde reduziert. Anstatt für alle Nutzer ein monolithisches Bundle zu aktivieren, wird nur der Code für die von Ihnen verwendeten Funktionen zur Laufzeit 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 Protokolle: Die Fehlerbehebung und Protokollierung wurden erheblich verbessert. Fehlerbehebungsprotokolle sind standardmäßig aktiviert, wenn Workbox von einem localhost-Ursprung aus verwendet wird und alle Protokollierung und Assertions aus den Produktions-Builds entfernt werden. Ein Beispiel für das Debugging-Logging in Workbox v3.
  • Verbessertes Webpack-Plug-in workbox-webpack-plugin lässt sich enger in den Webpack-Build-Prozess einbinden. Dies ermöglicht einen konfigurationsfreien Anwendungsfall, 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 vorgenommen werden.

Wichtige Änderungen

Build-Konfiguration

Die folgenden Änderungen wirken sich auf das Verhalten aller unserer Build-Tools (workbox-build, workbox-cli, workbox-webpack-plugin) mit gemeinsamen Konfigurationsoptionen aus.

  • Der 'fastest'-Handler-Name 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, durch die ein Build fehlschlägt, wenn eine ungültige Konfiguration verwendet wird. Eine Liste der derzeit unterstützten Optionen finden Sie in der Dokumentation zu runtimeCaching.

workbox-background-sync

  • Der maxRetentionTime-Konfigurationsparameter wird jetzt als Anzahl von Minuten und nicht als Anzahl von Millisekunden interpretiert.
  • Es gibt nun einen erforderlichen String, der den Warteschlangennamen darstellt. Dieser String muss beim Erstellen der Plug-in-Klasse oder der eigenständigen Klasse als erster Parameter übergeben werden. (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 nun einen erforderlichen String, der den Kanalnamen darstellt. Dieser muss beim Erstellen der Plug-in-Klasse oder der eigenständigen Klasse als erster Parameter übergeben werden.

In Version 2 wird beispielsweise die Plug-in-Klasse wie folgt initialisiert:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

Die entsprechende Verwendung in v3 sieht folgendermaßen aus:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

Informationen zur aktualisierten API-Oberfläche finden Sie in der Dokumentation.

workbox-build

  • Der glob-Musterabgleich wird nun standardmäßig mit den Optionen follow: true (die Symlinks folgen) und strict: true (weniger tolerant gegenüber "ungewöhnlichen" Fehlern) durchgeführt. Sie können beides deaktivieren und zum vorherigen Verhalten zurückkehren. Legen Sie dazu globFollow: false und/oder globStrict: false in der Build-Konfiguration fest.
  • Alle Funktionen in workbox-build geben in den Antworten das zusätzliche Attribut warnings zurück. Einige Szenarien, die in Version 2 als schwerwiegende Fehler behandelt wurden, sind jetzt zulässig, werden aber über das String-Array warnings gemeldet.

In Version 2 können Sie generateSW wie folgt 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}`));

Obwohl Sie in Version 3 denselben Code verwenden können, ist es eine gute Idee, nach warnings zu suchen und sie 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 in Version 2 ihre eigenen benutzerdefinierten ManifestTransform-Funktionen geschrieben haben, müssen das Manifest-Array in einem Objekt zurückgeben.Statt return manifestArray; sollten Sie also return {manifest: manifestArray}; verwenden. Dann kann Ihr Plug-in eine optionale warnings-Eigenschaft einschließen. Dies sollte ein Array von Strings mit nicht schwerwiegenden Warnungen sein.

Wenn Sie in Version 2 eine benutzerdefinierte ManifestTransform schreiben, schreiben 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 für:

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. Das zurückgegebene Promise enthält jetzt zusätzliche Informationen zu den vorab im Cache gespeicherten URLs.

Code wie der folgende in v2:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

können in Version 3 wie folgt 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 die Antwort zu verwenden, um Daten im entsprechenden Format auf das Laufwerk zu schreiben.

workbox-cache-expiration

  • Die Plug-in-API ist unverändert geblieben und wird von den meisten Entwicklern verwendet. Es gibt jedoch erhebliche API-Änderungen, die sich auf Entwickler auswirken, die die API 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ärskript wird nicht mehr unterstützt. Auf das Binärprogramm kann jetzt nur noch als workbox zugegriffen werden.
  • Die Befehle generate:sw und inject:manifest der Version 2 wurden in Version 3 in generateSW und injectManifest umbenannt.
  • In Version 2 wurde angenommen, dass sich die Standardkonfigurationsdatei (wird verwendet, wenn eine Datei nicht explizit angegeben wurde) im aktuellen Verzeichnis als workbox-cli-config.js festgelegt hat. In Version 3 ist es workbox-config.js.

Zusammengenommen bedeutet dies für Version 2 Folgendes:

$ workbox inject:manifest

das „Manifest einfügen“, mit einer aus workbox-cli-config.js gelesenen Konfiguration und in Version 3 so:

$ workbox injectManifest

wird dasselbe tun, aber liest die Konfiguration aus workbox-config.js.

Workbox-Precaching

  • Bei der Methode precache() wurden zuvor sowohl die Cache-Änderungen als auch das Routing für die Bereitstellung von im Cache gespeicherten Einträgen eingerichtet. Jetzt ändert precache() nur Cache-Einträge. Außerdem wurde die neue Methode addRoute() verfügbar gemacht, um eine Route für diese im Cache gespeicherten Antworten zu registrieren. Entwickler, die die vorherige Zwei-in-1-Funktion nutzen möchten, können zum Aufrufen von precacheAndRoute() wechseln.
  • Mehrere Optionen, die früher über den Konstruktor WorkboxSW konfiguriert wurden, werden jetzt als options-Parameter in workbox.precaching.precacheAndRoute([...], options) übergeben. Die Standardeinstellungen für diese Optionen sind in den Referenzdokumenten aufgeführt, wenn sie nicht konfiguriert sind.
  • Standardmäßig werden URLs ohne Dateiendung automatisch auf Übereinstimmungen mit einem Cache-Eintrag mit der Erweiterung .html geprüft. Wenn beispielsweise eine Anfrage für /path/to/index erfolgt (was nicht vorab im Cache gespeichert ist) und es einen vorab im Cache gespeicherten Eintrag für /path/to/index.html gibt, wird dieser vorab im Cache gespeicherte Eintrag verwendet. Entwickler können dieses neue Verhalten deaktivieren, indem sie {cleanUrls: false} bei der Übergabe von Optionen an workbox.precaching.precacheAndRoute() festlegen.
  • workbox-broadcast-update wird nicht mehr automatisch so konfiguriert, dass Cache-Aktualisierungen für vorab im Cache gespeicherte Assets angekündigt werden.

Der folgende Code in Version 2:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

hat ein v3-Äquivalent für:

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 zuvor über den Namespace workbox.router.* eines WorkboxSW-Objekts verwendet haben, müssen zum neuen Namespace workbox.routing.* wechseln.
  • Die Routen werden jetzt in der Reihenfolge der Erstregistrierung bewertet. Dies ist die gegenteilige Reihenfolge der Auswertung von Route, die in Version 2 verwendet wurde. Dabei hat die zuletzt registrierte Route Vorrang.
  • Die ExpressRoute-Klasse und Unterstützung für "Express-style" Platzhalter 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 eines RegExp, das mit einem Teil oder der gesamten Anfrage-URL übereinstimmt, kann eine Route auslösen.
  • Die Hilfsmethode addFetchListener() der Klasse Router wurde entfernt. Entwickler können entweder explizit ihren 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 auf einer einzelnen Route ausgeführt werden, wurden nicht geändert. Entwickler, die mehrere Routen gleichzeitig registrieren oder abmelden müssen, sollten stattdessen eine Reihe von Aufrufen an registerRoute() oder unregisterRoute() ausführen.

Der folgende Code in Version 2:

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 für:

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 „workbox-runtime-caching“)

  • Das workbox-runtime-caching-Modul heißt jetzt workbox-strategies und wurde unter dem neuen Namen auf npm veröffentlicht.
  • Die Verwendung des Cache-Ablaufs in einer Strategie ohne gleichzeitige 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 zu ablaufenden Einträgen im Standardcache führen, was unerwartet ist. In Version 3 kann ein Cache-Name ist 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 eigene Plug-ins geschrieben, die auf cacheWillMatch reagiert haben.
  • Die Syntax für die Angabe von Plug-ins beim Konfigurieren einer Strategie hat sich geändert. Jedes Plug-in muss explizit im Attribut plugins der Strategiekonfiguration aufgeführt sein.

Der folgende Code in Version 2:

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 für:

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 erhalten Sie im Abschnitt Verwenden von Plug-ins .

Workbox-Sw

  • Im Grunde wurde workbox-sw als einfaches Ladeprogramm umgeschrieben. Schnittstelle, die eine grundlegende Konfiguration erfordert und dafür verantwortlich ist, die anderen Module einzufügen, 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 bereitgestellt wird.

Zuvor in Version 2:

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 Version 3 müssen Sie nur das Skript workbox-sw.js importieren. Dann steht im globalen Namespace automatisch eine einsatzbereite Instanz als workbox zur Verfügung:

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 WorkboxSW-Konstruktor übergeben werden. Stattdessen wurden sie in die Methoden workbox.clientsClaim() und workbox.skipWaiting() geändert.
  • Die handleFetch-Option, 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 Funktion Umgehen für Netzwerk verwenden. die in den Entwicklertools von Chrome verfügbar ist.
Die Option „Für Netzwerk umgehen“ in den Chrome-Entwicklertools.

workbox-webpack-plugin

Das Plug-in wurde grundlegend umgeschrieben und kann in vielen Fällen in einer Nullkonfiguration verwendet werden. . Informationen zur aktualisierten API-Oberfläche finden Sie in der Dokumentation.

  • Die API stellt jetzt zwei Klassen bereit: GenerateSW und InjectManifest. Dadurch wird das Wechseln zwischen Modi explizit und im Vergleich zum Verhalten von Version 2, 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 und es ist nicht mehr erforderlich, globPatterns zu konfigurieren. Du solltest globPatterns nur weiterhin verwenden, wenn du Assets vorab im Cache speichern musst, die nicht in deinem Webpack-Build enthalten sind. Im Allgemeinen sollten Sie bei der Migration zum Plug-in Version 3 zuerst die gesamte vorherige glob-basierte Konfiguration entfernen und sie nur dann wieder hinzufügen, wenn Sie sie wirklich benötigen.

Hilfe erhalten

Wir gehen davon aus, dass die meisten Migrationen unkompliziert sein werden. Wenn Probleme auftreten, die in dieser Anleitung nicht behandelt werden, eröffnen Sie ein Problem auf GitHub.