Migracja z Workbox v2 do v3

Ten przewodnik skupia się na zmianach powodujących niezgodność wprowadzone w Workbox v3. Zawiera on przykłady zmian, które należy wprowadzić przy przejściu z konfiguracji Workbox v2.

Jeśli używasz starszej kombinacji sw-precache/sw-toolbox i chcesz po raz pierwszy przejść na korzystanie z Workbox, zapoznaj się z innym przewodnikiem po migracji.

Tło w wersji 3

Wersja 3 Workbox wprowadza istotne zmiany w bieżącej bazie kodu. Nadrzędne cele to:

  • Zminimalizuj rozmiar obszaru roboczego. Ilość pobieranego i wykonywanego kodu środowiska wykonawczego skryptu service worker została zmniejszona. Zamiast udostępniać wszystkim pakiet monolityczny, importowany jest tylko kod używanych przez Ciebie funkcji w czasie działania.
  • Workbox ma sieć CDN. Jako kanoniczną opcję dostępu do bibliotek środowiska wykonawczego Workbox zapewniamy w pełni obsługiwany hosting CDN oparty na Google Cloud Storage, co ułatwia korzystanie z Workbox.
  • Ulepszone debugowanie i logi. Środowisko debugowania i logowania zostało znacznie ulepszone. Logi debugowania są domyślnie włączone za każdym razem, gdy używana jest usługa Workbox z punktu początkowego localhost, a z kompilacji produkcyjnych usuwane są wszystkie logowanie i potwierdzenia. Przykładowe logowanie debugowania oferowane przez Workbox v3.
  • Ulepszona wtyczka pakietu internetowego. workbox-webpack-plugin ściśle integruje się z procesem kompilacji pakietu internetowego, co pozwala na zerową konfigurację, gdy chcesz wstępnie buforować wszystkie zasoby w potoku kompilacji.

Osiągnięcie tych celów i usunięcie pewnych aspektów poprzedniego interfejsu, które wydawały się niezręczne lub doprowadziło do powstania antywzorców, wymagało wprowadzenia w wersji 3 kilku istotnych zmian.

Niezbędne zmiany

Konfiguracja kompilacji

Poniższe zmiany wpływają na działanie wszystkich naszych narzędzi do kompilacji (workbox-build, workbox-cli, workbox-webpack-plugin), które mają wspólny zestaw opcji konfiguracji.

  • Podczas konfigurowania runtimeCaching nazwa modułu obsługi 'fastest' była wcześniej prawidłowa i jest traktowana jako alias dla 'staleWhileRevalidate'. Jest już nieważna, a deweloperzy powinni przejść bezpośrednio na korzystanie z 'staleWhileRevalidate'.
  • Zaktualizowano kilka nazw właściwości runtimeCaching.options i wprowadzono dodatkową weryfikację parametrów, która w przypadku użycia nieprawidłowej konfiguracji spowoduje niepowodzenie kompilacji. Listę obecnie obsługiwanych opcji znajdziesz w dokumentacji dotyczącej runtimeCaching.

workbox-background-sync

  • Parametr konfiguracji maxRetentionTime jest teraz interpretowany jako liczba minut, a nie liczba milisekund.
  • Występuje teraz wymagany ciąg znaków reprezentujący nazwę kolejki, który należy przekazać jako pierwszy parametr podczas tworzenia wtyczki lub samodzielnej klasy. (została wcześniej przekazana jako właściwość opcji). Zapoznaj się z dokumentacją dotyczącą zaktualizowanego interfejsu API.

workbox-broadcast-cache-update

  • Występuje teraz wymagany ciąg znaków reprezentujący nazwę kanału, który należy przekazać jako pierwszy parametr podczas tworzenia wtyczki lub samodzielnej klasy.

Na przykład w wersji 2 zainicjujesz klasę wtyczki w taki sposób:

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

Odpowiednik w wersji 3:

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

Zapoznaj się z dokumentacją dotyczącą zaktualizowanego interfejsu API.

workbox-build

  • Domyślnie dopasowywanie do wzorca glob będzie teraz wykonywane z opcjami follow: true (które są powiązane z linkami symbolicznymi) i strict: true (co mniej toleruje nietypowe błędy). Możesz wyłączyć dowolny z tych sposobów i wrócić do poprzedniego sposobu działania, ustawiając w konfiguracji kompilacji ustawienia globFollow: false lub globStrict: false.
  • Wszystkie funkcje dostępne w tabeli workbox-build zwracają w zwracanych odpowiedziach dodatkową właściwość warnings. Niektóre scenariusze, które w wersji 2 były uznawane za błędy krytyczne, są teraz dozwolone, ale są zgłaszane za pomocą tablicy warnings, która jest tablicą ciągów znaków.

W wersji 2 możesz nazwać generateSW w ten sposób:

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}`));

Możesz użyć tego samego kodu w wersji v3, ale warto też sprawdzić i zapisać warnings:

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}`));
  • Programiści, którzy napisali własne niestandardowe funkcje ManifestTransform w wersji 2, muszą zwracać tablicę manifestu w obiekcie (np. zamiast return manifestArray; użyj return {manifest: manifestArray};).mDzięki temu wtyczka może dołączyć opcjonalną właściwość warnings, która powinna być tablicą ciągów zawierających niekrytyczne informacje ostrzegawcze.

Jeśli tworzysz niestandardowy ManifestTransform w wersji 2, użyj takiego kodu:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

ma odpowiednik v3:

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: []};
};
  • Nazwa funkcji getFileManifestEntries() została zmieniona na getManifest(), a zwracana obietnica zawiera teraz dodatkowe informacje o adresach URL, które są wstępnie buforowane.

Kod podobny do tego w wersji 2:

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

można zapisać w wersji 3 tak:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.
  • Funkcja generateFileManifest() została usunięta. Zachęcamy deweloperów do wywoływania interfejsu getManifest() i używania jego odpowiedzi do zapisywania danych na dysku w odpowiednim formacie.

workbox-cache-expiration

  • Interfejs API wtyczek pozostał niezmieniony, czyli trybu, z którego korzysta większość deweloperów. Wprowadziliśmy jednak istotne zmiany dotyczące interfejsu API, które mają wpływ na deweloperów, którzy używają go jako samodzielnej klasy. Zapoznaj się z dokumentacją dotyczącą zaktualizowanego interfejsu API.

workbox-cli

Deweloperzy mogą uruchamiać interfejs wiersza poleceń z flagą --help, aby uzyskać pełny zestaw obsługiwanych parametrów.

  • Wycofaliśmy obsługę aliasu workbox-cli skryptu binarnego. Plik binarny jest teraz dostępny tylko jako workbox.
  • Polecenia generate:sw i inject:manifest w wersji 2 zostały w niej zmienione na generateSW i injectManifest.
  • W wersji 2 przyjęto, że domyślny plik konfiguracji (używany, gdy plik nie został wyraźnie udostępniony) w bieżącym katalogu to workbox-cli-config.js. W wersji 3 jest to workbox-config.js.

Łącznie oznacza to, że w wersji 2:

$ workbox inject:manifest

uruchomiłoby „wstrzyknięcie pliku manifestu” procesu kompilacji, używając konfiguracji odczytanej z interfejsu workbox-cli-config.js oraz w wersji 3:

$ workbox injectManifest

zrobi to samo, ale odczyta konfigurację ze strony workbox-config.js.

wstępne wczytywanie do pamięci roboczej

  • Metoda precache() wcześniej wprowadzała zmiany w pamięci podręcznej oraz konfigurowała routing na potrzeby wyświetlania wpisów z pamięci podręcznej. Obecnie precache() modyfikuje tylko wpisy pamięci podręcznej, a nowa metoda (addRoute()) została udostępniona do zarejestrowania trasy służącej do udostępniania tych odpowiedzi w pamięci podręcznej. Deweloperzy, którzy chcą korzystać z poprzedniej funkcji „2 w jednym”, mogą przejść na wywoływanie funkcji precacheAndRoute().
  • Kilka opcji, które wcześniej były konfigurowane za pomocą konstruktora WorkboxSW, jest teraz przekazywanych jako parametr options w narzędziu workbox.precaching.precacheAndRoute([...], options). Wartości domyślne tych opcji (jeśli nie są skonfigurowane) znajdziesz w dokumentach referencyjnych.
  • Domyślnie adresy URL bez rozszerzenia pliku są automatycznie sprawdzane pod kątem dopasowania do wpisu w pamięci podręcznej zawierającego rozszerzenie .html. Jeśli na przykład żądanie wysłane do /path/to/index (które nie jest wstępnie buforowane) i istnieje wpis w pamięci podręcznej dla /path/to/index.html, zostanie on użyty. Deweloperzy mogą wyłączyć to nowe zachowanie, ustawiając {cleanUrls: false} podczas przekazywania opcji do workbox.precaching.precacheAndRoute().
  • Interfejs workbox-broadcast-update nie będzie już automatycznie skonfigurowany do ogłaszania aktualizacji pamięci podręcznej dla zasobów w pamięci podręcznej.

W wersji 2 ten kod:

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

ma odpowiednik v3:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

planowanie tras roboczych

  • Deweloperzy, którzy wcześniej używali workbox-routing w przestrzeni nazw workbox.router.* obiektu WorkboxSW, muszą przełączyć się na nową przestrzeń nazw (workbox.routing.*).
  • Trasy są teraz oceniane w kolejności, w której wygrywają użytkownicy. Jest to odwrotna kolejność oceny Route, która była używana w wersji 2, w której pierwszeństwo ma ostatnia zarejestrowana wartość Route.
  • Klasa ExpressRoute i obsługa typu „Express” i zostały usunięte. Spowoduje to znaczne zmniejszenie rozmiaru pliku workbox-routing. Ciągi znaków użyte jako pierwszy parametr w polu workbox.routing.registerRoute() będą teraz traktowane jako dopasowania ścisłe. Dopasowania wieloznaczne lub częściowe powinny być obsługiwane przez operatory RegExp. Użycie dowolnego parametru RegExp, który pasuje do części lub całości adresu URL żądania, może aktywować trasę.
  • Metoda pomocnicza addFetchListener() klasy Router została usunięta. Deweloperzy mogą bezpośrednio dodać własny moduł obsługi fetch lub użyć interfejsu udostępnianego przez workbox.routing, co spowoduje automatyczne utworzenie modułu obsługi fetch.
  • Metody registerRoutes() i unregisterRoutes() zostały usunięte. Wersje tych metod, które działają w pojedynczym obiekcie Route, nie uległy zmianie, a deweloperzy, którzy chcą zarejestrować lub wyrejestrować wiele tras jednocześnie, powinni wykonać serię wywołań funkcji registerRoute() lub unregisterRoute().

W wersji 2 ten kod:

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()
);

ma odpowiednik v3:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

strategie dotyczące modułów roboczych (dawniej buforowanie obszaru roboczego)

  • Moduł workbox-runtime-caching nazywa się teraz workbox-strategies i został opublikowany npm pod nową nazwą.
  • Użycie okresu ważności pamięci podręcznej w strategii bez podania nazwy pamięci podręcznej nie jest już prawidłowe. W wersji 2 było to możliwe:
workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Z tego powodu wpisy w domyślnej pamięci podręcznej mogą tracić ważność, co jest nieoczekiwane. W wersji v3 nazwa pamięci podręcznej jest wymagane:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
  • Nazwa metody cyklu życia cacheWillMatch została zmieniona na cachedResponseWillBeUsed. Nie powinna to być widoczna zmiana dla programistów, chyba że napisali własne wtyczki, które zareagowały na cacheWillMatch.
  • Zmieniła się składnia służąca do określania wtyczek podczas konfigurowania strategii. Każda wtyczka musi być wyraźnie wskazana we właściwości plugins konfiguracji strategii.

W wersji 2 ten kod:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

ma odpowiednik v3:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

Więcej informacji znajdziesz w artykule „Korzystanie z wtyczek”. Google.

Workbox-SW

  • Aplikacja workbox-sw została przebudowana i jest prostsza w obsłudze który wymaga podstawowej konfiguracji i odpowiada za pobieranie innych modułów potrzebnych w czasie działania. Zamiast tworzyć nową instancję klasy WorkboxSW, deweloperzy będą wchodzić w interakcje z dotychczasową instancją, która jest automatycznie udostępniana w globalnej przestrzeni nazw.

Wcześniej w wersji 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(...);

W wersji 3 wystarczy zaimportować skrypt workbox-sw.js, a gotowa do użycia instancja będzie automatycznie dostępna w globalnej przestrzeni nazw jako workbox:

importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);
  • Opcje skipWaiting i clientsClaim nie są już opcjami przekazywanymi do konstruktora WorkboxSW. Zostały one zmienione na metody workbox.clientsClaim() i workbox.skipWaiting().
  • Opcja handleFetch, która była wcześniej obsługiwana w konstruktorze wersji 2, nie jest już obsługiwana w wersji 3. Deweloperzy, którzy potrzebują podobnej funkcji, aby przetestować skrypt service worker bez wywoływania żadnych modułów obsługi pobierania, mogą użyć opcji „Pomiń dla sieci”. w Narzędziach deweloperskich w Chrome.
Opcja „Omijaj dla sieci” w Narzędziach deweloperskich w Chrome

workbox-webpack-plugin

Wtyczka została znacząco przeredagowana i w wielu przypadkach można jej używać w „konfiguracji zerowej”. i trybu uzyskiwania zgody. Zapoznaj się z dokumentacją dotyczącą zaktualizowanego interfejsu API.

  • Interfejs API udostępnia teraz 2 klasy: GenerateSW i InjectManifest. Dzięki temu przełączanie trybów jest jawne, a w wersji 2 zachowanie zmienia się zależnie od obecności elementu swSrc.
  • Domyślnie zasoby w potoku kompilacji pakietu internetowego są wstępnie zapisywane w pamięci podręcznej i nie trzeba już konfigurować globPatterns. Korzystanie z globPatterns jest możliwe tylko wtedy, gdy musisz wstępnie buforować zasoby, które nie są zawarte w kompilacji pakietu internetowego. Ogólnie podczas migracji do wtyczki w wersji 3 należy zacząć od usunięcia całej konfiguracji opartej na glob i dodać ją ponownie tylko w razie potrzeby.

Uzyskiwanie pomocy

Przewidujemy, że migracja w większości przypadków będzie prosta. Jeśli napotkasz problemy, których nie omówiliśmy w tym przewodniku, daj nam znać, otwierając zgłoszenie na GitHubie.