Параметр navigateFallbackWhitelist: фильтрация маршрутов

Библиотека sw-precache используется для генерации сервис-воркеров, которые кэшируют статические ресурсы и обеспечивают оффлайн-доступ к веб-приложению. Одним из ключевых аспектов настройки сервис-воркера является управление маршрутизацией запросов HTML-страниц, особенно при использовании одностраничных приложений (SPA), где все пути обычно обрабатываются одним index.html.

Параметр navigateFallbackWhitelist предназначен для точечной фильтрации URL-адресов, которые должны использовать fallback-маршрут, определённый в параметре navigateFallback. Это позволяет более гибко управлять тем, какие запросы перенаправляются на основной HTML-файл, а какие остаются «чистыми» и не перехватываются сервис-воркером.

Назначение navigateFallbackWhitelist

В простейшем случае сервис-воркер с navigateFallback будет перенаправлять все навигационные запросы на один HTML-файл:

navigateFallback: '/index.html'

Это удобно для SPA, но приводит к проблемам, если:

  • Есть отдельные API-запросы, которые используют метод GET для JSON.
  • Некоторые внешние маршруты не должны обрабатываться сервис-воркером.
  • Необходимо исключить динамические страницы с определёнными паттернами.

В таких случаях используется navigateFallbackWhitelist, который принимает массив регулярных выражений (RegExp). Только URL, соответствующие этим шаблонам, будут перенаправлены на navigateFallback.

Синтаксис

navigateFallbackWhitelist: [
  new RegExp('^/app/'),       // Все маршруты, начинающиеся с /app/
  new RegExp('^/dashboard')   // Все маршруты, начинающиеся с /dashboard
]

Принцип работы:

  1. Запрос приходит в сервис-воркер.
  2. Проверяется, является ли он навигационным (event.request.mode === 'navigate').
  3. Если да, то URL сверяется с каждым регулярным выражением из navigateFallbackWhitelist.
  4. Если совпадение найдено, происходит возврат navigateFallback.
  5. Если совпадения нет — запрос продолжается обычным образом, без использования fallback.

Примеры использования

Пример 1: Ограничение SPA-маршрутов

swPrecache.write('service-worker.js', {
  staticFileGlobs: [
    'dist/**/*.js',
    'dist/**/*.css',
    'dist/**/*.html'
  ],
  navigateFallback: '/index.html',
  navigateFallbackWhitelist: [
    /^\/app\//,       // Только маршруты, начинающиеся с /app/
    /^\/profile\//    // и маршруты с /profile/
  ]
});

В этом примере:

  • /app/home и /profile/settings будут перенаправлены на /index.html.
  • /api/data или /external/page останутся без изменения, запрос будет выполнен напрямую.

Пример 2: Исключение API и статических ресурсов

navigateFallbackWhitelist: [
  /^\/(?!api\/)/,  // Все маршруты, кроме начинающихся с /api/
]

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

Особенности и рекомендации

  • Порядок регулярных выражений имеет значение: sw-precache проверяет их последовательно. Первый совпавший шаблон решает, что использовать fallback.
  • Использовать строгие паттерны: слишком широкие регулярные выражения могут привести к неожиданной переадресации.
  • Совместимость с navigateFallback: navigateFallbackWhitelist работает только если navigateFallback задан.
  • Отладка через DevTools: для проверки правильности фильтрации полезно использовать вкладку Application → Service Workers и наблюдать за запросами.

Отличие от navigateFallbackBlacklist

В sw-precache есть аналогичный параметр navigateFallbackBlacklist, который работает обратным образом:

  • navigateFallbackBlacklist исключает URL из обработки fallback.
  • navigateFallbackWhitelist разрешает fallback только для URL, подходящих под шаблоны.

Использование whitelist предпочтительнее, когда требуется строгий контроль над тем, какие маршруты SPA обрабатываются сервис-воркером, а какие нет.

Практические советы

  1. Для SPA лучше сочетать navigateFallback и navigateFallbackWhitelist, чтобы исключить API и внешние пути.
  2. Если сайт имеет много разных страниц, удобно создавать массив регулярных выражений с комментариями для каждого маршрута.
  3. Регулярные выражения должны учитывать только путь URL, без домена и query-параметров.
  4. Для сложных случаев можно комбинировать whitelist и blacklist через кастомные проверки в событии fetch, но это уже выходит за рамки стандартной настройки sw-precache.

Таким образом, параметр navigateFallbackWhitelist является инструментом точечной фильтрации маршрутов при использовании сервис-воркера, позволяя контролировать, какие URL перенаправляются на основной HTML-файл, а какие обрабатываются обычным образом. Это обеспечивает баланс между оффлайн-доступностью и корректной работой динамических ресурсов.

Оглавление