Параметр runtimeCaching: структура и назначение

Параметр runtimeCaching в библиотеке Sw-precache предназначен для описания стратегий кэширования ресурсов, которые не были заранее добавлены в precache-манифест. В отличие от статического кэширования (precache), где список файлов фиксируется на этапе сборки, runtimeCaching управляет поведением service worker во время выполнения — при перехвате сетевых запросов.

Основная задача — определить, как обрабатывать запросы к динамическим ресурсам: API, изображениям, сторонним скриптам, шрифтам и другим данным, которые появляются уже после установки service worker.

Общая структура

runtimeCaching представляет собой массив объектов, каждый из которых описывает правило обработки запросов:

runtimeCaching: [
  {
    urlPattern: /\/api\/.*$/,
    handler: 'networkFirst',
    options: {
      cacheName: 'api-cache',
      expiration: {
        maxEntries: 50,
        maxAgeSeconds: 300
      }
    }
  }
]

Каждый объект включает три ключевых элемента:

  • urlPattern — шаблон URL для перехвата
  • handler — стратегия кэширования
  • options — дополнительные параметры настройки

Поле urlPattern

Определяет, какие запросы будут обрабатываться данным правилом. Поддерживаются разные типы значений:

Регулярные выражения

Наиболее распространённый способ:

urlPattern: /\/images\/.*\.(png|jpg|jpeg|svg)$/

Строки

Используются для точного совпадения:

urlPattern: '/api/data'

Функции

Позволяют реализовать сложную логику:

urlPattern: function({ url, event }) {
  return url.origin === 'https://api.example.com';
}

Функция получает объект с параметрами запроса (url, event, request) и должна возвращать true или false.

Поле handler

Определяет стратегию кэширования. Sw-precache предоставляет несколько встроенных стратегий:

cacheFirst

Сначала пытается взять ресурс из кэша, при отсутствии — обращается к сети.

Применение:

  • изображения
  • шрифты
  • статические ассеты
handler: 'cacheFirst'

networkFirst

Сначала делает запрос к сети, при неудаче — возвращает кэшированную версию.

Применение:

  • API-запросы
  • часто обновляемые данные
handler: 'networkFirst'

fastest

Параллельно делает запрос к сети и кэшу, возвращает первый полученный ответ.

Применение:

  • компромисс между скоростью и актуальностью
handler: 'fastest'

networkOnly

Всегда обращается к сети, игнорируя кэш.

handler: 'networkOnly'

cacheOnly

Возвращает только кэшированные данные.

handler: 'cacheOnly'

Поле options

Позволяет детально настроить поведение кэширования.

cacheName

Имя кэша, в котором будут храниться ресурсы:

options: {
  cacheName: 'image-cache'
}

Разделение кэшей облегчает управление и очистку.

expiration

Контроль времени жизни и размера кэша:

options: {
  expiration: {
    maxEntries: 100,
    maxAgeSeconds: 86400
  }
}
  • maxEntries — максимальное количество записей
  • maxAgeSeconds — срок хранения в секундах

При превышении лимитов старые записи автоматически удаляются.

cacheableResponse

Фильтрация ответов, которые можно кэшировать:

options: {
  cacheableResponse: {
    statuses: [0, 200]
  }
}

Позволяет исключить ошибки или нежелательные ответы.

fetchOptions

Настройки запроса fetch:

options: {
  fetchOptions: {
    credentials: 'include'
  }
}

Используется для управления куки, CORS и другими параметрами.

matchOptions

Настройки поиска в кэше:

options: {
  matchOptions: {
    ignoreSearch: true
  }
}

Позволяет игнорировать query-параметры при поиске ресурса.

Приоритет правил

Массив runtimeCaching обрабатывается сверху вниз. При совпадении с первым подходящим urlPattern дальнейшие правила игнорируются.

runtimeCaching: [
  {
    urlPattern: /\/api\/.*/,
    handler: 'networkFirst'
  },
  {
    urlPattern: /\/api\/special\/.*/,
    handler: 'cacheFirst'
  }
]

В данном случае второй обработчик никогда не будет применён, поскольку первый перехватывает все запросы /api/.

Комбинирование стратегий

Часто используется несколько правил для разных типов ресурсов:

runtimeCaching: [
  {
    urlPattern: /\/api\/.*$/,
    handler: 'networkFirst',
    options: {
      cacheName: 'api-cache'
    }
  },
  {
    urlPattern: /\.(?:png|jpg|jpeg|svg)$/,
    handler: 'cacheFirst',
    options: {
      cacheName: 'image-cache',
      expiration: {
        maxEntries: 60
      }
    }
  },
  {
    urlPattern: /https:\/\/fonts\.googleapis\.com\/.*/,
    handler: 'cacheFirst',
    options: {
      cacheName: 'google-fonts'
    }
  }
]

Обработка сторонних ресурсов

runtimeCaching особенно важен для ресурсов с других доменов:

{
  urlPattern: /^https:\/\/cdn\.example\.com\/.*$/,
  handler: 'cacheFirst',
  options: {
    cacheName: 'cdn-cache'
  }
}

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

Особенности работы с API

Для API-запросов обычно применяется networkFirst, но с таймаутом:

{
  urlPattern: /\/api\/.*$/,
  handler: 'networkFirst',
  options: {
    networkTimeoutSeconds: 3,
    cacheName: 'api-cache'
  }
}

Если сеть не отвечает в течение указанного времени, используется кэш.

Влияние на производительность

Грамотно настроенный runtimeCaching:

  • снижает нагрузку на сеть
  • ускоряет повторные загрузки
  • улучшает офлайн-доступность
  • уменьшает задержки при плохом соединении

Ошибки в настройке могут привести к:

  • устаревшим данным
  • переполнению кэша
  • конфликтам между правилами

Типичные сценарии использования

Статические изображения:

handler: 'cacheFirst'

REST API:

handler: 'networkFirst'

CDN-библиотеки:

handler: 'cacheFirst'

HTML-страницы:

handler: 'networkFirst'

Взаимодействие с precache

runtimeCaching дополняет precache:

  • precache — для файлов сборки (JS, CSS, HTML)
  • runtimeCaching — для динамических и внешних ресурсов

Оба механизма работают совместно внутри service worker.

Отладка и контроль

Для проверки работы runtimeCaching используется:

  • вкладка Application → Cache Storage в DevTools
  • логирование service worker
  • отключение сети для тестирования fallback-логики

Ограничения

  • не поддерживает сложные пользовательские стратегии без расширения
  • ограничен возможностями Service Worker API
  • требует аккуратного проектирования для предотвращения конфликтов

Расширение через кастомные обработчики

Хотя handler принимает строковые значения, возможно внедрение пользовательской логики через обёртки и модификации service worker, генерируемого Sw-precache.

Это позволяет реализовать:

  • fallback-страницы
  • кастомную логику обновления
  • сложные сценарии кэширования

Роль в архитектуре PWA

runtimeCaching является ключевым элементом для:

  • офлайн-режима
  • оптимизации загрузки
  • управления сетевыми запросами
  • создания устойчивого пользовательского опыта при нестабильной сети
Оглавление