Workbox-Precaching

Ein Feature von Service Workern ist die Möglichkeit, eine Reihe von Dateien im Cache zu speichern, wenn der Service Worker installiert wird. Dies wird oft als "Precaching" bezeichnet, da Sie Inhalte vor dem verwendeten Service Worker im Cache speichern.

Der Hauptgrund dafür ist, dass Entwickler damit die Kontrolle über den Cache haben. Sie können so feststellen, wann und wie lange eine Datei im Cache gespeichert wird, und sie an den Browser senden, ohne das Netzwerk zu nutzen. So können sie Web-Apps erstellen, die offline ausgeführt werden.

Workbox entlastet das Precaching erheblich, indem es die API vereinfacht und dafür sorgt, dass Assets effizient heruntergeladen werden.

Funktionsweise der Workbox-Precaching

Wenn eine Web-App zum ersten Mal geladen wird, prüft workbox-precaching alle Assets, die Sie herunterladen möchten, entfernt alle Duplikate und verbindet die entsprechenden Service Worker-Ereignisse zum Herunterladen und Speichern der Assets. URLs, die bereits Versionsinformationen wie einen Inhalts-Hash enthalten, werden ohne weitere Änderungen als Cache-Schlüssel verwendet. Bei URLs, die keine Versionsinformationen enthalten, ist an ihren Cache-Schlüssel ein zusätzlicher URL-Suchparameter angehängt, der einen Hash ihrer Inhalte darstellt, den Workbox bei der Build-Erstellung generiert.

workbox-precaching führt all dies während des install-Ereignisses des Service Workers aus.

Wenn ein Nutzer Ihre Webanwendung später noch einmal aufruft und Sie einen neuen Service Worker mit anderen vorab im Cache gespeicherten Assets haben, prüft workbox-precaching die neue Liste und ermittelt anhand der Überarbeitung, welche Assets komplett neu sind und welche der vorhandenen Assets aktualisiert werden müssen. Alle neuen Assets oder Aktualisierungen von Versionen werden dem Cache während des install-Ereignisses des neuen Service Workers hinzugefügt.

Dieser neue Service Worker wird erst dann zum Antworten auf Anfragen verwendet, wenn das entsprechende activate-Ereignis ausgelöst wurde. Im activate-Ereignis sucht workbox-precaching nach im Cache gespeicherten Assets, die nicht mehr in der Liste der aktuellen URLs vorhanden sind, und entfernt diese aus dem Cache.

workbox-precaching führt diese Schritte bei jeder Installation und Aktivierung des Service Workers aus, um sicherzustellen, dass der Nutzer über die neuesten Assets verfügt, und lädt nur die geänderten Dateien herunter.

Vorab im Cache gespeicherte Antworten bereitstellen

Durch den Aufruf von precacheAndRoute() oder addRoute() wird eine Route erstellt, die Anfragen für vorab im Cache gespeicherte URLs entspricht.

Die in dieser Route verwendete Antwortstrategie ist cache-first: Die vorab im Cache gespeicherte Antwort wird verwendet, es sei denn, die Antwort im Cache ist aufgrund eines unerwarteten Fehlers nicht vorhanden. In diesem Fall wird stattdessen eine Netzwerkantwort verwendet.

Es ist wichtig, in welcher Reihenfolge Sie precacheAndRoute() oder addRoute() aufrufen. Normalerweise sollten Sie ihn früh in der Service Worker-Datei aufrufen, bevor Sie zusätzliche Routen mit registerRoute() registrieren. Wenn Sie zuerst registerRoute() aufgerufen haben und diese Route einer eingehenden Anfrage entspricht, wird für die Antwort die Strategie verwendet, die Sie in dieser zusätzlichen Route definiert haben, und nicht die von workbox-precaching verwendete Cache-First-Strategie.

Erläuterung der Precache-Liste

workbox-precaching erwartet ein Array von Objekten mit den Attributen url und revision. Dieses Array wird manchmal als Precache-Manifest bezeichnet:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

Diese Liste verweist auf eine Reihe von URLs mit jeweils eigenen Überarbeitungsinformationen.

Für das zweite und dritte Objekt im Beispiel oben ist das Attribut revision auf null gesetzt. Das liegt daran, dass sich die Informationen zur Überarbeitung in der URL selbst befinden, was im Allgemeinen eine Best Practice für statische Assets ist.

Das erste Objekt (/index.html) legt explizit ein Überarbeitungsattribut fest, bei dem es sich um einen automatisch generierten Hash des Dateiinhalts handelt. Im Gegensatz zu JavaScript- und CSS-Ressourcen können HTML-Dateien in ihren URLs in der Regel keine Überarbeitungsinformationen enthalten. Andernfalls funktionieren Links zu diesen Dateien im Web jedes Mal, wenn sich der Inhalt der Seite ändert.

Durch die Übergabe einer Überarbeitungseigenschaft an precacheAndRoute() weiß Workbox, wann sich die Datei geändert hat, und kann die Datei entsprechend aktualisieren.

Workbox enthält Tools, mit denen Sie diese Liste erstellen können:

• workbox-build: Dies ist ein Knotenpaket, das in einer Gulp-Aufgabe oder als npm-Ausführungsskript verwendet werden kann.
• workbox-webpack-plugin: Webpack-Nutzer können dieses Plug-in verwenden.
• workbox-cli: Mit der Befehlszeile können Sie auch die Liste der Assets generieren und Ihrem Service Worker hinzufügen.

Eingehende Anfragen für vorab im Cache gespeicherte Dateien

Eine Sache, die workbox-precaching standardmäßig ausführt, ist die Manipulation der eingehenden Netzwerkanfragen, um vorab im Cache gespeicherte Dateien abzugleichen. Dies ermöglicht die Verwendung gängiger Praktiken im Web.

Eine Anfrage für / kann beispielsweise in der Regel von der Datei unter /index.html erfüllt werden.

Im Folgenden finden Sie eine Liste der Bearbeitungen, die workbox-precaching standardmäßig ausführt, und wie Sie dieses Verhalten ändern können.

URL-Parameter ignorieren

Anfragen mit Suchparametern können so geändert werden, dass bestimmte Werte oder alle Werte entfernt werden.

Standardmäßig werden Suchparameter, die mit utm_ beginnen oder genau mit fbclid übereinstimmen, entfernt. Das bedeutet, dass eine Anfrage für /about.html?utm_campaign=abcd mit einem vorab im Cache gespeicherten Eintrag für /about.html erfüllt wird.

Andere Suchparameter können Sie mit ignoreURLParametersMatching ignorieren:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    // Ignore all URL parameters.
    ignoreURLParametersMatching: [/.*/],
  }
);

Verzeichnisindex

Anfragen, die mit / enden, werden standardmäßig mit Einträgen abgeglichen, an deren Ende ein index.html angehängt ist. Das bedeutet, dass eine eingehende Anfrage für / automatisch mit dem vorab im Cache gespeicherten Eintrag /index.html verarbeitet werden kann.

Sie können sie ändern oder vollständig deaktivieren, indem Sie directoryIndex festlegen:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    directoryIndex: null,
  }
);

Bereinigte URLs

Wenn eine Anfrage nicht mit dem Vorcache übereinstimmt, fügen wir am Ende .html hinzu, um „saubere“ URLs (auch „pretty“ URLs genannt) zu unterstützen. Das bedeutet, dass eine Anfrage wie /about vom vorab im Cache gespeicherten Eintrag für /about.html verarbeitet wird.

Sie können dieses Verhalten deaktivieren, indem Sie cleanUrls festlegen:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([{url: '/about.html', revision: 'b79cd4'}], {
  cleanUrls: false,
});

Benutzerdefinierte Manipulationen

Wenn Sie benutzerdefinierte Übereinstimmungen von eingehenden Anfragen mit vorab im Cache gespeicherten Assets definieren möchten, können Sie dies mit der Option urlManipulation tun. Dies sollte ein Callback sein, der ein Array möglicher Übereinstimmungen zurückgibt.

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    urlManipulation: ({url}) => {
      // Your logic goes here...
      return [alteredUrlOption1, alteredUrlOption2];
    },
  }
);

Erweiterte Nutzung

PrecacheController direkt verwenden

Standardmäßig richtet workbox-precaching die Listener install und activate für Sie ein. Für Entwickler, die mit Service Workern vertraut sind, ist dies möglicherweise nicht empfehlenswert, wenn sie mehr Kontrolle benötigen.

Anstatt den Standardexport zu verwenden, können Sie direkt mit dem PrecacheController Elemente zum Vorcache hinzufügen und feststellen, wann diese Assets installiert und wann eine Bereinigung stattfinden soll.

import {PrecacheController} from 'workbox-precaching';

const precacheController = new PrecacheController();
precacheController.addToCacheList([
  {url: '/styles/example-1.abcd.css', revision: null},
  {url: '/styles/example-2.1234.css', revision: null},
  {url: '/scripts/example-1.abcd.js', revision: null},
  {url: '/scripts/example-2.1234.js', revision: null},
]);

precacheController.addToCacheList([{
  url: '/index.html',
  revision: 'abcd',
}, {
  url: '/about.html',
  revision: '1234',
}]);

self.addEventListener('install', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.install(event));
});

self.addEventListener('activate', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.activate(event));
});

self.addEventListener('fetch', (event) => {
  const cacheKey = precacheController.getCacheKeyForURL(event.request.url);
  event.respondWith(caches.match(cacheKey).then(...));
});

Vorab im Cache gespeicherte Assets direkt lesen

Es kann vorkommen, dass Sie ein vorab im Cache gespeichertes Asset direkt außerhalb des Kontexts des Routings lesen müssen, das workbox-precaching automatisch ausführen kann. Sie können beispielsweise HTML-Vorlagen teilweise im Cache speichern, die dann abgerufen und beim Erstellen einer vollständigen Antwort verwendet werden müssen.

Im Allgemeinen können Sie die Cache Storage API verwenden, um die vorab im Cache gespeicherten Response-Objekte abzurufen. Es gibt jedoch eine Falten: Der URL-Cache-Schlüssel, der beim Aufruf von cache.match() verwendet werden muss, kann einen Versionsverwaltungsparameter enthalten, den workbox-precaching automatisch erstellt und verwaltet.

Um den richtigen Cache-Schlüssel zu erhalten, können Sie getCacheKeyForURL() aufrufen, die ursprüngliche URL übergeben und dann das Ergebnis verwenden, um einen cache.match() für den entsprechenden Cache auszuführen.

import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cache = await caches.open(cacheNames.precache);
const response = await cache.match(getCacheKeyForURL('/precached-file.html'));

Wenn Sie nur das vorab im Cache gespeicherte Response-Objekt benötigen, können Sie alternativ matchPrecache() aufrufen, das automatisch den richtigen Cache-Schlüssel verwendet und im richtigen Cache sucht:

import {matchPrecache} from 'workbox-precaching';

const response = await matchPrecache('/precached-file.html');

Alte Precaches bereinigen

Die meisten Workbox-Releases haben dasselbe Format für die Speicherung von vorab im Cache gespeicherten Daten. Außerdem können Vor-Caches, die von älteren Versionen von Workbox erstellt wurden, von neueren Versionen in der Regel unverändert verwendet werden. In seltenen Fällen gibt es jedoch eine funktionsgefährdende Änderung beim Precaching des Speichers, sodass bestehende Nutzer alles noch einmal herunterladen müssen und zuvor vorab zwischengespeicherte Daten überflüssig machen. Eine solche Änderung gab es zwischen den Workbox-Versionen v3 und v4.

Diese veralteten Daten dürften den normalen Betrieb nicht beeinträchtigen, tragen aber zu Ihrer Gesamtnutzung des Speicherkontingents bei und es kann für Ihre Nutzer einfacher sein, sie explizit zu löschen. Fügen Sie dazu Ihrem Service Worker cleanupOutdatedCaches() hinzu oder legen Sie cleanupOutdatedCaches: true fest, wenn Sie den Service Worker mit einem der Build-Tools von Workbox generieren.

Unterressourcenintegrität verwenden

Einige Entwickler möchten möglicherweise die zusätzlichen Garantien, die von der Erzwingung der Unterressourcenintegrität angeboten werden, wenn vorab im Cache gespeicherte URLs aus dem Netzwerk abgerufen werden.

Die zusätzliche, optionale Eigenschaft integrity kann jedem Eintrag im Precache-Manifest hinzugefügt werden. Wenn angegeben, wird sie beim Erstellen des Request zum Füllen des Cache als integrity-Wert verwendet. Bei einer Abweichung schlägt der Precaching-Prozess fehl.

In den Build-Tools von Workbox kann nicht ermittelt werden, welche Pre-Cache-Manifesteinträge integrity-Attribute haben sollen und welche geeigneten Werte verwendet werden sollen. Entwickler, die diese Funktion aktivieren möchten, sollten stattdessen das von Workbox generierte Precache-Manifest ändern, um die entsprechenden Informationen selbst hinzuzufügen. Die Option manifestTransform in der Konfiguration der Build-Tools von Workbox kann Abhilfe schaffen:

const ssri = require('ssri');

const integrityManifestTransform = (originalManifest, compilation) => {
  const warnings = [];
  const manifest = originalManifest.map(entry => {
    // If some criteria match:
    if (entry.url.startsWith('...')) {
      // This has to be a synchronous function call, for example:
      // compilation will be set when using workbox-webpack-plugin.
      // When using workbox-build directly, you can read the file's
      // contents from disk using, e.g., the fs module.
      const asset = compilation.getAsset(entry.url);
      entry.integrity = ssri.fromData(asset.source.source()).toString();

      // Push a message to warnings if needed.
    }
    return entry;
  });

  return {warnings, manifest};
};

// Then add manifestTransform: [integrityManifestTransform]
// to your Workbox build configuration.

workbox-precaching.urlManipulation(
  { url }: object,
)

workbox-precaching.addPlugins(
  plugins: WorkboxPlugin[],
)

workbox-precaching.addRoute(
  options?: PrecacheRouteOptions,
)

workbox-precaching.cleanupOutdatedCaches()

workbox-precaching.createHandlerBoundToURL(
  url: string,
)

workbox-precaching.getCacheKeyForURL(
  url: string,
)

workbox-precaching.matchPrecache(
  request: string | Request,
)

workbox-precaching.precache(
  entries: (string | PrecacheEntry)[],
)

workbox-precaching.precacheAndRoute(
  entries: (string | PrecacheEntry)[],
  options?: PrecacheRouteOptions,
)