Migracja z Workbox v2 do v3

W tym przewodniku skupiliśmy się na oznaczaniu zmian wprowadzonych w Workbox v3. Zawiera on przykłady zmian, które trzeba wprowadzić podczas uaktualniania konfiguracji Workbox v2.

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

Tło wersja 3

Wersja 3 Workbox zawiera istotne refaktoryzowanie istniejącej bazy kodu. Nadrzędne cele to:

  • Zmniejsz rozmiar pola roboczego. Zmniejszono ilość pobieranego i wykonywanego kodu środowiska wykonawczego skryptu service worker. Zamiast zezwalać wszystkim na korzystanie z pakietu monolitycznego, w czasie działania importowany będzie tylko kod funkcji, z której korzystasz.
  • Pole robocze ma sieć CDN. Oferujemy w pełni obsługiwany hosting CDN oparty na Google Cloud Storage jako kanoniczną opcję dostępu do bibliotek środowiska wykonawczego Workbox, co ułatwia rozpoczęcie korzystania z Workbox.
  • Lepsze debugowanie i dzienniki. Znacznie ulepszyliśmy obsługę debugowania i logowania. Logi debugowania są domyślnie włączone za każdym razem, gdy używana jest usługa Workbox ze źródła localhost, a wszystkie logowania i potwierdzenia są usuwane z kompilacji produkcyjnych. Przykład logowania debugowania oferowanego przez Workbox w wersji 3.
  • Ulepszona wtyczka pakietu internetowego. workbox-webpack-plugin integruje się ściślej z procesem kompilacji pakietu Webpack, co pozwala uniknąć braku konfiguracji, gdy chcesz wstępnie buforować wszystkie zasoby w potoku kompilacji.

Osiągnięcie tych celów i porządkowanie niektórych aspektów poprzedniego interfejsu, które sprawiały wrażenie dziwnych lub doprowadzały do antywzorców, wymagały wprowadzenia w wersji 3 kilku przełomowych zmian.

Niezbędne zmiany

Konfiguracja kompilacji

Te 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.

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

proces-synchronizacji w tle

  • 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 klasy niezależnej. (która wcześniej była przekazywana jako właściwość opcji). Więcej informacji o zaktualizowanej powierzchni interfejsu API znajdziesz w dokumentacji.

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 klasy niezależnej.

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

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

Odpowiednik w wersji 3 wygląda tak:

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

Więcej informacji o zaktualizowanej powierzchni interfejsu API znajdziesz w dokumentacji.

tworzenie okna roboczego

  • Domyślnie dopasowywanie do wzorca glob będzie teraz przeprowadzane z opcjami follow: true (które pojawiają się po dowiązaniach symbolicznych) i strict: true (która jest mniej tolerancyjna na „nietypowe” błędy). Możesz wyłączyć dowolne z nich i wrócić do poprzedniego działania, ustawiając parametr globFollow: false lub globStrict: false w konfiguracji kompilacji.
  • Wszystkie funkcje w polu workbox-build zwracają w zwracanych odpowiedziach dodatkową właściwość – warnings. Niektóre scenariusze, które w wersji 2 zostały uznane za błędy krytyczne, są teraz dozwolone, ale są raportowane za pomocą tablicy warnings, która jest tablicą ciągów znaków.

W wersji 2 możesz wywołać funkcję 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}`));

W wersji 3 możesz użyć tego samego kodu, ale warto sprawdzić warnings i zarejestrować je:

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}`));
  • Deweloperzy, którzy utworzyli własne niestandardowe funkcje ManifestTransform w wersji 2, muszą zwracać w obiekcie tablicę manifestu (np. zamiast return manifestArray; należy użyć parametru return {manifest: manifestArray};). Dzięki temu wtyczka może uwzględnić opcjonalną właściwość warnings, która powinna być tablicą ciągów znaków zawierających ostrzeżenia o niekrytycznych błędach.

Jeśli tworzysz niestandardowy obiekt 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 wersji 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 zwrócona obietnica zawiera teraz dodatkowe informacje o adresach URL w pamięci podręcznej.

Kod podobny do tego w wersji 2:

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

można przepisać w wersji 3 w taki sposób:

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 funkcji getManifest() i używania jej odpowiedzi do zapisywania danych na dysku w odpowiednim formacie.

workbox-cache-expiration

  • Interfejs Plugin API nie zmienił się, czyli trybu, z którego korzysta większość programistów. W interfejsie API występują jednak istotne zmiany wpływające na programistów, którzy używają go jako samodzielnej klasy. Więcej informacji o zaktualizowanej powierzchni interfejsu API znajdziesz w dokumentacji.

workbox-cli

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

  • Obsługa aliasu workbox-cli skryptu binarnego została wycofana. Plik binarny jest teraz dostępny tylko jako workbox.
  • Polecenia w wersji 2 generate:sw i inject:manifest zostały zmienione na generateSW i injectManifest w wersji 3.
  • W wersji 2 domyślny plik konfiguracji (używany, gdy plik nie został jawnie podany) został przyjęty jako workbox-cli-config.js w bieżącym katalogu. W wersji 3 jest to workbox-config.js.

Zebrane razem oznaczają, że w wersji 2:

$ workbox inject:manifest

uruchomi proces kompilacji „inject manifest” przy użyciu konfiguracji odczytanej z workbox-cli-config.js oraz w wersji 3:

$ workbox injectManifest

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

wstępne buforowanie zgodnie ze skrzynką roboczą

  • Metoda precache() wcześniej zarówno modyfikowała pamięć podręczną, jak i skonfigurować routing do obsługi wpisów z pamięci podręcznej. Obecnie precache() modyfikuje tylko wpisy w pamięci podręcznej, a nowa metoda (addRoute()) została ujawniona, aby zarejestrować trasę obsługi odpowiedzi z pamięci podręcznej. Deweloperzy, którzy chcą korzystać z poprzedniej, funkcji 2 w 1, mogą przejść na wywoływanie funkcji precacheAndRoute().
  • Kilka opcji, które wcześniej było konfigurowane za pomocą konstruktora WorkboxSW, jest teraz przekazywanych jako parametr options w workbox.precaching.precacheAndRoute([...], options). Wartości domyślne tych opcji, jeśli nie są skonfigurowane, znajdziesz w dokumentacji referencyjnej.
  • Domyślnie adresy URL bez rozszerzenia pliku są automatycznie sprawdzane pod kątem dopasowania do wpisu w pamięci podręcznej z rozszerzeniem .html. Jeśli na przykład wysłano żądanie dotyczące /path/to/index (które nie jest wstępnie zapisane w pamięci podręcznej) i istnieje wpis dla /path/to/index.html w pamięci podręcznej, zostanie użyty ten wpis w pamięci podręcznej. Deweloperzy mogą wyłączyć to nowe zachowanie, ustawiając zasady {cleanUrls: false} podczas przekazywania opcji do interfejsu workbox.precaching.precacheAndRoute().
  • Komponent workbox-broadcast-update nie będzie już automatycznie skonfigurowany do informowania o aktualizacjach pamięci podręcznej zasobów wstępnie zapisanych w pamięci podręcznej.

Ten kod w wersji 2:

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

ma odpowiednik wersji v3:

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

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

kierowanie ruchem w skrzynkach roboczych

  • Deweloperzy, którzy wcześniej używali workbox-routing za pomocą przestrzeni nazw workbox.router.* obiektu WorkboxSW, muszą przejść na nową przestrzeń nazw: workbox.routing.*.
  • Trasy są teraz oceniane w kolejności, w której dana osoba wygrywa. Jest to odwrotna kolejność oceny funkcji Route, która była używana w wersji 2, gdzie pierwszeństwo ma właściwość Route zarejestrowana jako ostatnia.
  • Klasa ExpressRoute i obsługa symboli wieloznacznych „Express-style” zostały usunięte. To znacznie zmniejsza rozmiar pliku workbox-routing. Ciągi tekstowe użyte jako pierwszy parametr funkcji workbox.routing.registerRoute() będą teraz traktowane jako dopasowania ścisłe. Dopasowania częściowe lub symbole wieloznaczne powinny być obsługiwane przez komponenty RegExp – przy użyciu elementów RegExp, które pasują do części lub całego adresu URL żądania, mogą aktywować trasę.
  • Metoda pomocnicza addFetchListener() klasy Router została usunięta. Deweloperzy mogą samodzielnie dodać własny moduł obsługi fetch lub użyć interfejsu udostępnianego przez workbox.routing, który domyślnie utworzy dla nich moduł obsługi fetch.
  • Metody registerRoutes() i unregisterRoutes() zostały usunięte. Wersje tych metod, które działają na pojedynczym obiekcie Route, nie uległy zmianie. Deweloperzy, którzy chcą zarejestrować lub wyrejestrować kilka tras jednocześnie, powinni wykonać serię wywołań funkcji registerRoute() lub unregisterRoute().

Ten kod w wersji 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()
);

ma odpowiednik wersji v3:

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

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

strategie skrzynki roboczej (dawniej nazywane buforowaniem środowiska wykonawczego)

  • Moduł workbox-runtime-caching obecnie oficjalnie nazywa się workbox-strategies i został opublikowany npm pod nową nazwą.
  • Używanie wygaśnięcia pamięci podręcznej w strategii bez podawania nazwy pamięci podręcznej już nie działa. W wersji 2 było to możliwe:
workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Spowoduje to wygaszanie ważności wpisów w domyślnej pamięci podręcznej, co jest nieoczekiwane. W wersji 3 nazwa pamięci podręcznej jest wymagana:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
  • Metoda cyklu życia cacheWillMatch została zmieniona na cachedResponseWillBeUsed. Zmiana ta nie powinna być widoczna dla deweloperów, chyba że stworzyli oni własne wtyczki, które zareagowały na cacheWillMatch.
  • Składnia, która służy do określania wtyczek podczas konfigurowania strategii, zmieniła się. Każda wtyczka musi być wyraźnie wymieniona we właściwości plugins konfiguracji strategii.

Ten kod w wersji 2:

const workboxSW = new self.WorkboxSW();

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

ma odpowiednik wersji 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 przewodniku „Korzystanie z wtyczek”.

Workbox-sw

  • Interfejs workbox-sw został napisany na nowo, aby powstał lekki interfejs „modułu ładowania”, który wymaga podstawowej konfiguracji i odpowiada za pobieranie innych modułów wymaganych w czasie działania. Zamiast tworzyć nową instancję klasy WorkboxSW, deweloperzy będą wchodzić w interakcję z dotychczasową instancją, która jest automatycznie wyświetlana w globalnej przestrzeni nazw.

Poprzednio 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ż przekazywane do konstruktora WorkboxSW. Zamiast tego zostały zmienione na metody workbox.clientsClaim() i workbox.skipWaiting().
  • Opcja handleFetch, która była wcześniej obsługiwana w konstruktorze w wersji 2, nie jest już obsługiwana w wersji 3. Deweloperzy, którzy potrzebują podobnej funkcji do przetestowania skryptu service worker bez wywoływania żadnych modułów obsługi pobierania, mogą użyć opcji „Pomiń dla sieci” dostępnej w Narzędziach dla programistów w Chrome.
Opcja Pominięcie dla sieci w Narzędziach deweloperskich w Chrome.

workbox-webpack-plugin

Wtyczka została w znacznym stopniu przeredagowana i w wielu przypadkach można ich używać w trybie „zerowej konfiguracji”. Więcej informacji o zaktualizowanej powierzchni interfejsu API znajdziesz w dokumentacji.

  • Interfejs API udostępnia teraz 2 klasy: GenerateSW i InjectManifest. Sprawia to, że przełączanie trybów jest jawne, a nie działa w wersji 2, w których działanie zmieniało się na podstawie obecności atrybutu swSrc.
  • Domyślnie zasoby w potoku kompilacji pakietu internetowego są wstępnie buforowane i nie trzeba już konfigurować globPatterns. Jedynym powodem, dla którego warto dalej korzystać z usługi globPatterns, jest konieczność wstępnego buforowania zasobów, które nie są uwzględnione w kompilacji pakietu internetowego. Ogólnie podczas migracji do wtyczki w wersji 3 należy najpierw usunąć całą poprzednią konfigurację opartą na glob i dodać ją ponownie tylko wtedy, gdy będzie Ci potrzebna.

Uzyskiwanie pomocy

Przewidujemy, że większość migracji będzie prosta. Jeśli napotkasz problemy, które nie zostały opisane w tym przewodniku, daj nam znać, otwierając je na GitHubie.