Эта страница переведена с помощью Cloud Translation API.

Миграция с Workbox v2 на v3,Миграция с Workbox v2 на v3

Это руководство посвящено критическим изменениям, внесенным в Workbox v3, и содержит примеры того, какие изменения необходимо внести при обновлении с установки Workbox v2.

Если вы в настоящее время используете устаревшую комбинацию sw-precache / sw-toolbox и хотите впервые перейти на Workbox, вот другое руководство по миграции , которое вам поможет.

v3 Фон

Версия Workbox v3 представляет собой значительный рефакторинг существующей кодовой базы. Главными целями являются:

Уменьшите размер рабочей области. Объем загружаемого и выполняемого кода Service Worker был уменьшен. Вместо того, чтобы включать всех в монолитный пакет, во время выполнения будет импортироваться только код для конкретных функций, которые вы используете.
Workbox имеет CDN. Мы предоставляем полностью поддерживаемый хостинг CDN на базе Google Cloud Storage в качестве канонического варианта доступа к библиотекам времени выполнения Workbox, что упрощает запуск и работу с Workbox.
Улучшенная отладка и журналы. Значительно улучшены возможности отладки и ведения журнала. Журналы отладки включены по умолчанию всякий раз, когда Workbox используется из localhost источника, а все журналы и утверждения удаляются из производственных сборок.
Улучшен плагин веб-пакета. workbox-webpack-plugin более тесно интегрируется с процессом сборки веб-пакета, позволяя использовать вариант без настройки, когда вы хотите предварительно кэшировать все ресурсы в конвейере сборки.

Достижение этих целей и исправление некоторых аспектов предыдущего интерфейса, которые казались неудобными или приводили к антипаттернам, потребовали внесения ряда критических изменений в версию v3.

Критические изменения

Конфигурация сборки

Следующие изменения влияют на поведение всех наших инструментов сборки ( workbox-build , workbox-cli , workbox-webpack-plugin ), которые имеют общий набор параметров конфигурации.

Имя 'fastest' обработчика ранее было допустимым и рассматривалось как псевдоним для 'staleWhileRevalidate' при настройке runtimeCaching . Он больше не действителен, и разработчикам следует напрямую перейти на использование 'staleWhileRevalidate' .
Были обновлены имена нескольких свойств runtimeCaching.options , а также введена дополнительная проверка параметров, которая приведет к сбою сборки, если используется недопустимая конфигурация. См. документацию по runtimeCaching для получения списка поддерживаемых в настоящее время опций.

синхронизация фона рабочей области

Параметр конфигурации maxRetentionTime теперь интерпретируется как количество минут, а не как количество миллисекунд.
Теперь существует обязательная строка, представляющая имя очереди, которую необходимо передать в качестве первого параметра при создании плагина или автономного класса. (Ранее оно было передано как свойство параметров.) Обновленную поверхность API см. в документации .

обновление рабочего ящика-вещания-кэша

Теперь существует обязательная строка, представляющая имя канала, которую необходимо передать в качестве первого параметра при создании плагина или автономного класса.

Например, в версии 2 вы инициализируете класс плагина следующим образом:

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

Эквивалентное использование в v3:

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

Обратитесь к документации по обновленной поверхности API.

сборка рабочего ящика

По умолчанию сопоставление шаблонов glob теперь будет выполняться со следующими параметрами follow: true (которые будут следовать за символическими ссылками) и strict: true (которые менее устойчивы к «необычным» ошибкам). Вы можете отключить любой из них и вернуться к предыдущему поведению, установив globFollow: false и/или globStrict: false в конфигурации сборки.
Все функции в workbox-build возвращают дополнительное свойство warnings в возвращаемых ими ответах. Некоторые сценарии, которые в версии 2 рассматривались как фатальные ошибки, теперь разрешены, но о них сообщается через warnings , которые представляют собой массив строк.

В версии 2 вы можете generateSW следующим образом:

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

Хотя вы можете использовать тот же код в версии 3, рекомендуется проверять наличие 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}`));

Разработчикам, которые написали свои собственные функции ManifestTransform в v2, необходимо вернуть массив манифеста в объекте (т.е. вместо return manifestArray; вы должны использовать return {manifest: manifestArray}; ).mЭто позволяет вашему плагину включать необязательное свойство warnings , которое должен быть массивом строк, содержащих нефатальную предупреждающую информацию.

Если вы писали собственный ManifestTransform в версии 2, используйте такой код:

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

имеет эквивалент 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: []};
};

Функция getFileManifestEntries() была переименована в getManifest() , а возвращаемое обещание теперь включает дополнительную информацию о предварительно кэшированных URL-адресах.

Код, подобный следующему в версии 2:

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

можно переписать в v3 как:

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

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.

Функция generateFileManifest() была удалена. Разработчикам рекомендуется вместо этого вызывать getManifest() и использовать его ответ для записи данных на диск в соответствующем формате.

срок действия кэша рабочего ящика

API плагина остался прежним, и именно этот режим в конечном итоге будет использовать большинство разработчиков. Однако есть существенные изменения API, влияющие на разработчиков, использующих его как отдельный класс. Обратитесь к документации по обновленной поверхности API.

рабочий ящик-кли

Разработчики могут запускать CLI с флагом --help для получения полного набора поддерживаемых параметров.

Поддержка псевдонима workbox-cli для двоичного сценария удалена. Доступ к двоичному файлу теперь возможен только как workbox .
Команды generate:sw и inject:manifest были переименованы generateSW и injectManifest в v3.
В версии 2 предполагалось, что файл конфигурации по умолчанию (используемый, если он не был указан явно) — workbox-cli-config.js в текущем каталоге. В версии 3 это workbox-config.js .

В совокупности это означает, что в версии 2:

$ workbox inject:manifest

запустит процесс сборки «внедрить манифест», используя конфигурацию, считанную из workbox-cli-config.js , и в версии 3:

$ workbox injectManifest

сделает то же самое, но прочитает конфигурацию из workbox-config.js .

предварительное кэширование рабочего ящика

Метод precache() ранее выполнял как модификации кэша, так и настройку маршрутизации для обслуживания кэшированных записей. Теперь precache() изменяет только записи кэша, а новый метод addRoute() предназначен для регистрации маршрута для обслуживания этих кэшированных ответов. Разработчики, которым нужна предыдущая функциональность «два в одном», могут переключиться на вызов precacheAndRoute() .
Несколько параметров, которые раньше настраивались через конструктор WorkboxSW , теперь передаются в качестве параметра options в workbox.precaching.precacheAndRoute([...], options) . Значения по умолчанию для этих параметров, если они не настроены, перечислены в справочной документации .
По умолчанию URL-адреса, у которых нет расширения файла, автоматически проверяются на соответствие записи кэша, содержащей расширение .html . Например, если сделан запрос для /path/to/index (который не предварительно кэширован) и существует предварительно кэшированная запись для /path/to/index.html , эта предварительно кэшированная запись будет использоваться. Разработчики могут отключить это новое поведение, установив {cleanUrls: false} при передаче параметров в workbox.precaching.precacheAndRoute() .
workbox-broadcast-update больше не будет автоматически настраиваться для объявления обновлений кэша для предварительно кэшированных ресурсов.

Следующий код в v2:

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

имеет эквивалент v3:

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

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

маршрутизация рабочего ящика

Разработчикам, которые ранее использовали workbox-routing через пространство имен Workbox.router workbox.router.* объекта WorkboxSW, необходимо переключиться на новое пространство имен, workbox.routing.* .
Маршруты теперь оцениваются в порядке первых зарегистрированных побед. Это порядок оценки Route , противоположный тому, который использовался в версии 2, где приоритет будет отдаваться последнему зарегистрированному Route .
Класс ExpressRoute и поддержка подстановочных знаков в стиле Express были удалены . Это значительно уменьшает размер workbox-routing . Строки, используемые в качестве первого параметра для workbox.routing.registerRoute() теперь будут рассматриваться как точные совпадения. Подстановочные знаки или частичные совпадения должны обрабатываться с помощью RegExp — использование любого RegExp , совпадающего с частью или всем URL-адресом запроса, может инициировать маршрут.
Вспомогательный метод addFetchListener() класса Router был удален. Разработчики могут либо явно добавить свой собственный обработчик fetch , либо использовать интерфейс, предоставляемый workbox.routing , который неявно создаст для них обработчик fetch .
Методы registerRoutes() и unregisterRoutes() были удалены. Версии этих методов, которые работают с одним Route не были изменены, и разработчикам, которым необходимо зарегистрировать или отменить регистрацию нескольких маршрутов одновременно, вместо этого следует выполнить серию вызовов метода registerRoute() или unregisterRoute() .

Следующий код в v2:

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

имеет эквивалент v3:

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

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

стратегии рабочего ящика (ранее известные как кэширование времени выполнения рабочего ящика)

Модуль workbox-runtime-caching теперь официально известен как workbox-strategies и опубликован на npm под новым названием.
Использование срока действия кэша в стратегии без указания имени кэша больше недопустимо. В v2 это было возможно:

workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Это приведет к истечению срока действия записей в кэше по умолчанию, что является неожиданным. В v3 требуется имя кэша:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});

Метод жизненного цикла cacheWillMatch был переименован в cachedResponseWillBeUsed . Это не должно быть заметным изменением для разработчиков, если только они не написали свои собственные плагины, реагирующие cacheWillMatch .
Изменился синтаксис указания плагинов при настройке стратегии. Каждый плагин должен быть явно указан в свойстве plugins конфигурации стратегии.

Следующий код в v2:

const workboxSW = new self.WorkboxSW();

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

имеет эквивалент 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]}),
  ],
});

Вы можете узнать больше в руководстве « Использование плагинов ».

рабочий ящик-программное обеспечение

«Под капотом» workbox-sw был переписан и стал облегченным интерфейсом «загрузчика», который требует некоторой базовой настройки и отвечает за подключение других модулей, необходимых во время выполнения. Вместо создания нового экземпляра класса WorkboxSW разработчики будут взаимодействовать с существующим экземпляром, который автоматически отображается в глобальном пространстве имен.

Ранее в версии 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(...);

В v3 вам просто нужно импортировать скрипт workbox-sw.js , и готовый к использованию экземпляр будет автоматически доступен в глобальном пространстве имен как workbox :

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

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);

skipWaiting и clientsClaim больше не являются параметрами, передаваемыми конструктору WorkboxSW . Вместо этого они были заменены методами workbox.clientsClaim() и workbox.skipWaiting() .
Параметр handleFetch , который ранее поддерживался в конструкторе версии 2, больше не поддерживается в версии 3. Разработчики, которым нужна аналогичная функциональность для тестирования своего сервис-воркера без вызова обработчиков выборки, могут использовать опцию « Обход сети », доступную в инструментах разработчика Chrome.

Параметр «Обход сети» в Chrome DevTools.

рабочийбокс-webpack-плагин

Плагин был существенно переписан и во многих случаях может использоваться в режиме «нулевой настройки». Обратитесь к документации по обновленной поверхности API.

API теперь предоставляет два класса: GenerateSW и InjectManifest . Это делает переключение между режимами явным, по сравнению с поведением версии 2, где поведение менялось в зависимости от присутствия swSrc .
По умолчанию ресурсы в конвейере компиляции веб-пакета будут предварительно кэшированы, и настраивать globPatterns больше не требуется. Единственная причина продолжать использовать globPatterns — это если вам нужно предварительно кэшировать ресурсы, которые не включены в сборку вашего веб-пакета. В общем, при переходе на плагин v3 вам следует начать с удаления всей вашей предыдущей конфигурации на основе glob и добавлять ее заново только в том случае, если она вам особенно нужна.

Получать помощь

Мы ожидаем, что большинство миграций будут простыми. Если у вас возникнут проблемы, не описанные в этом руководстве, сообщите нам об этом, открыв проблему на GitHub.