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. - 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 konfigurowaniaruntimeCaching
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 dokumentacjiruntimeCaching
.
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 opcjamifollow: true
(które pojawiają się po dowiązaniach symbolicznych) istrict: 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 parametrglobFollow: false
lubglobStrict: 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ą tablicywarnings
, 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. zamiastreturn manifestArray;
należy użyć parametrureturn {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 nagetManifest()
, 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 funkcjigetManifest()
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 jakoworkbox
. - Polecenia w wersji 2
generate:sw
iinject:manifest
zostały zmienione nagenerateSW
iinjectManifest
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 toworkbox-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. Obecnieprecache()
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 funkcjiprecacheAndRoute()
. - Kilka opcji, które wcześniej było konfigurowane za pomocą konstruktora
WorkboxSW
, jest teraz przekazywanych jako parametroptions
wworkbox.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 interfejsuworkbox.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 nazwworkbox.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 plikuworkbox-routing
. Ciągi tekstowe użyte jako pierwszy parametr funkcjiworkbox.routing.registerRoute()
będą teraz traktowane jako dopasowania ścisłe. Dopasowania częściowe lub symbole wieloznaczne powinny być obsługiwane przez komponentyRegExp
– przy użyciu elementówRegExp
, które pasują do części lub całego adresu URL żądania, mogą aktywować trasę. - Metoda pomocnicza
addFetchListener()
klasyRouter
została usunięta. Deweloperzy mogą samodzielnie dodać własny moduł obsługifetch
lub użyć interfejsu udostępnianego przezworkbox.routing
, który domyślnie utworzy dla nich moduł obsługifetch
. - Metody
registerRoutes()
iunregisterRoutes()
zostały usunięte. Wersje tych metod, które działają na pojedynczym obiekcieRoute
, nie uległy zmianie. Deweloperzy, którzy chcą zarejestrować lub wyrejestrować kilka tras jednocześnie, powinni wykonać serię wywołań funkcjiregisterRoute()
lubunregisterRoute()
.
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ł opublikowanynpm
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 nacachedResponseWillBeUsed
. Zmiana ta nie powinna być widoczna dla deweloperów, chyba że stworzyli oni własne wtyczki, które zareagowały nacacheWillMatch
. - 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ę klasyWorkboxSW
, 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
iclientsClaim
nie są już przekazywane do konstruktoraWorkboxSW
. Zamiast tego zostały zmienione na metodyworkbox.clientsClaim()
iworkbox.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.
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
iInjectManifest
. 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 atrybutuswSrc
. - 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ługiglobPatterns
, 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ą naglob
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.