Типичные ошибки при инициализации

Неправильный путь к скрипту Workbox Частая ошибка — указание некорректного пути к файлу workbox-sw.js. Если используется CDN, путь должен быть полным и точным:

importScripts('https://storage.googleapis.com/workbox-cdn/releases/6.7.0/workbox-sw.js');

Использование относительных путей к локальной копии библиотеки без проверки структуры проекта может приводить к тому, что сервис-воркер не загрузится, а ошибки в консоли браузера будут неочевидны. Важно убедиться, что файл доступен по указанному URL и возвращает корректный JavaScript.

Преждевременное использование Workbox Инициализация любых стратегий кэширования до загрузки скрипта Workbox вызывает ошибки workbox is not defined. Все обращения к объекту workbox должны выполняться после успешного импорта через importScripts. Типичный шаблон:

if (workbox) {
  workbox.routing.registerRoute(...);
} else {
  console.log('Workbox failed to load');
}

Ошибки при регистрации сервис-воркера

Неправильный scope при регистрации Указание некорректного scope при регистрации сервис-воркера приводит к тому, что правила кэширования не применяются к нужным ресурсам:

navigator.serviceWorker.register('/sw.js', { scope: '/app/' });

Если фактические ресурсы находятся вне /app/, сервис-воркер их не контролирует. Важно всегда проверять соответствие пути регистрации и структуры приложения.

Попытка регистрации несколько раз Многократная регистрация сервис-воркера без проверки может вызвать непредсказуемое поведение кэшей. Правильный подход — использовать существующий сервис-воркер или проверять его статус:

navigator.serviceWorker.getRegistration().then(reg => {
  if (!reg) {
    navigator.serviceWorker.register('/sw.js');
  }
});

Ошибки при создании стратегий кэширования

Смешение стратегий без понимания их особенностей Workbox предоставляет несколько стратегий: CacheFirst, NetworkFirst, StaleWhileRevalidate. Часто новичок пытается применить NetworkFirst к статическим ресурсам, что вызывает лишние сетевые запросы и медленную загрузку.

Неверное использование cacheName Одной из частых ошибок является использование одинакового имени кэша для разных ресурсов. Это приводит к конфликтам и потере данных:

workbox.routing.registerRoute(
  ({request}) => request.destination === 'image',
  new workbox.strategies.CacheFirst({
    cacheName: 'static-resources'
  })
);

workbox.routing.registerRoute(
  ({request}) => request.destination === 'script',
  new workbox.strategies.CacheFirst({
    cacheName: 'static-resources' // конфликт с предыдущим
  })
);

Лучше использовать отдельные имена кэшей для разных типов ресурсов.

Игнорирование версионирования кэша Без версионирования и обновления кэша старые ресурсы могут оставаться в кэше навсегда. Правильная практика:

const cacheVersion = 'v1';
const cacheName = `static-resources-${cacheVersion}`;

И при изменении версии ресурса обновлять cacheVersion для сброса старого кэша.

Ошибки при работе с precaching

Неправильное указание манифеста Использование workbox.precaching.precacheAndRoute() требует массива объектов с url и revision. Ошибки возникают, если revision отсутствует или не изменяется при обновлении ресурсов:

workbox.precaching.precacheAndRoute([
  { url: '/index.html', revision: '1234' }, // revision должен обновляться при изменении файла
]);

Попытка кэшировать динамический контент через precaching precaching предназначен для статических ресурсов, которые не изменяются во время работы приложения. Кэширование динамических данных таким способом приводит к устаревшему контенту и неконсистентности.

Ошибки при использовании событий сервис-воркера

Игнорирование событий install и activate Многие разработчики полагаются только на Workbox и не добавляют собственные обработчики событий, например для очистки старых кэшей:

self.addEventListener('activate', event => {
  const expectedCaches = ['static-resources-v1'];
  event.waitUntil(
    caches.keys().then(keys =>
      Promise.all(
        keys.map(key => {
          if (!expectedCaches.includes(key)) return caches.delete(key);
        })
      )
    )
  );
});

Без этого старые версии кэшей будут накапливаться и занимать место.

Ошибки в обработке fetch Если добавляется собственный обработчик fetch, он может конфликтовать с Workbox-роутингом. Нужно либо полностью контролировать маршруты, либо использовать workbox.routing.registerRoute для консистентности.

Эти ошибки встречаются наиболее часто и являются критическими для стабильной работы сервис-воркеров на базе Workbox. Правильная организация и последовательная проверка всех этапов — от загрузки скрипта до стратегий кэширования — позволяет избежать большинства проблем.

Оглавление