Параметр navigateFallbackBlacklist

navigateFallbackBlacklist является одной из ключевых опций при конфигурации библиотеки Sw-precache. Его основное назначение — предотвращение перехвата навигационных запросов сервис-воркером для определённых URL, когда одновременно используется navigateFallback.

Назначение и контекст

В Sw-precache navigateFallback задаёт файл, который будет возвращён при навигационных запросах, если соответствующий ресурс не найден в кэше или на сервере. Типичный пример — SPA (Single Page Application), где все маршруты должны обрабатываться одним HTML-файлом (обычно index.html).

Однако не все URL должны попадать под эту логику. Например, API-запросы, запросы к сторонним сервисам или статическим JSON-файлам не должны заменяться HTML-файлом приложения. Именно здесь появляется navigateFallbackBlacklist.

Тип значения

navigateFallbackBlacklist принимает массив регулярных выражений (RegExp). Каждый элемент массива проверяется на соответствие URL навигационного запроса. Если URL совпадает с хотя бы одним регулярным выражением, navigateFallback не применяется, и сервис-воркер пропускает запрос дальше.

navigateFallbackBlacklist: [
  /\/api\//,                 // не перехватывать все URL, начинающиеся с /api/
  /\/admin\//,               // исключение для административной панели
  /\.pdf$/                   // исключение для PDF-файлов
]

Поведение при совпадении

  • Если URL соответствует любому регулярному выражению из массива, сервис-воркер не возвращает navigateFallback.
  • Если URL не совпадает ни с одним выражением, сервис-воркер возвращает файл, указанный в navigateFallback.

Это позволяет гибко настраивать обработку навигационных запросов и исключать из неё определённые пути.

Практические рекомендации

  1. Ставить исключения для API и динамических ресурсов Любые запросы, которые должны возвращать реальные данные от сервера, следует включать в navigateFallbackBlacklist. Например:

    /\/api\//, /\/auth\//, /\.json$/

  2. Использовать точные регулярные выражения Чем точнее выражение, тем меньше риск случайного блокирования навигации. Не рекомендуется использовать слишком общие шаблоны вроде /\/.*/.

  3. Проверять порядок исключений Порядок элементов массива не критичен, так как проверка выполняется по принципу “совпадение хотя бы с одним выражением”. Однако для читаемости и поддержки проекта логично группировать исключения по типу ресурсов.

  4. Тестировать на всех маршрутах приложения После настройки navigateFallbackBlacklist важно проверить, что:

    • SPA правильно обрабатывает внутренние маршруты;
    • запросы к API и статическим файлам проходят без перехвата.

Взаимодействие с другими параметрами

  • navigateFallback — основной файл, возвращаемый при навигации.
  • navigateFallbackWhitelist — противоположная настройка, которая ограничивает применение fallback только указанными URL, тогда как blacklist исключает их.
  • runtimeCaching — отдельная настройка для динамического кэширования; blacklist гарантирует, что runtime-кэш не будет мешать навигационным запросам.

Пример полной конфигурации Sw-precache

swPrecache.write('service-worker.js', {
  staticFileGlobs: [
    'dist/**/*.js',
    'dist/**/*.css',
    'dist/index.html'
  ],
  stripPrefix: 'dist/',
  navigateFallback: '/index.html',
  navigateFallbackBlacklist: [
    /\/api\//,
    /\/auth\//,
    /\.pdf$/,
    /\/admin\//
  ],
  runtimeCaching: [
    {
      urlPattern: /\/images\//,
      handler: 'cacheFirst'
    }
  ]
});

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

  • Все внутренние маршруты SPA будут возвращать index.html.
  • Запросы к API, авторизации, PDF-файлам и административным страницам не будут перехватываться.
  • Изображения будут динамически кэшироваться по стратегии cacheFirst.

Ключевые выводы

  • navigateFallbackBlacklist — инструмент точечной настройки поведения навигационного fallback.
  • Используется только вместе с navigateFallback.
  • Основная цель — исключение определённых URL из перехвата сервис-воркером, чтобы сохранить корректную работу динамических ресурсов и внешних сервисов.

Эффективное использование navigateFallbackBlacklist повышает надёжность SPA и предотвращает неожиданные ошибки при работе с сервис-воркером.

Оглавление