Параметр directoryIndex

directoryIndex — это ключевой параметр конфигурации библиотеки Sw-precache, используемый для определения, какой файл должен обрабатываться как индекс директории при генерации сервис-воркера. Его назначение заключается в том, чтобы корректно разрешать URL-адреса, которые оканчиваются на слэш, на конкретный файл в файловой системе, обычно index.html.

Синтаксис и тип значения

swPrecache.write('service-worker.js', {
  staticFileGlobs: ['public/**.html', 'public/**.js', 'public/**.css'],
  directoryIndex: 'index.html'
});
  • Тип значения: строка
  • Пример: 'index.html'
  • Если параметр не задан, по умолчанию Sw-precache использует 'index.html'.

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

Когда браузер делает запрос к URL, который оканчивается на /, сервис-воркер будет пытаться сопоставить этот URL с конкретным файлом. Параметр directoryIndex определяет, какой файл считать индексным в этой директории.

Например:

  • URL запроса: /about/
  • Параметр directoryIndex: 'index.html'
  • Сервис-воркер будет искать файл: /about/index.html в кеше.

Если directoryIndex задан как пустая строка '', Sw-precache не будет автоматически добавлять индексный файл, и URL /about/ останется без преобразования.

Влияние на кеширование

directoryIndex напрямую влияет на формирование кеша для статических файлов. При использовании шаблона staticFileGlobs:

staticFileGlobs: [
  'public/**/*.html',
  'public/**/*.js',
  'public/**/*.css'
]

и параметра:

directoryIndex: 'index.html'

Сервис-воркер автоматически создаёт кеш не только для конкретных файлов, но и для всех директорий с индексными файлами.

Особенности использования

  1. Совместимость с SPA (Single Page Application) В SPA часто маршруты не соответствуют физической структуре директорий. Например, /dashboard/ физически не существует, но должен возвращать index.html. В таких случаях directoryIndex помогает правильно обслуживать маршруты через сервис-воркер.

  2. Переопределение имени индексного файла В проектах, где используется другой файл в качестве главного (например, main.html), можно указать:

    directoryIndex: 'main.html'

    В результате запрос к / или /about/ будет сопоставляться с main.html в соответствующей директории.

  3. Совмещение с stripPrefix и replacePrefix Параметр directoryIndex часто используется вместе с stripPrefix или replacePrefix, чтобы корректно формировать пути к файлам в кеше при разной структуре директорий:

    stripPrefix: 'public/',
directoryIndex: 'index.html'

    Это позволяет сохранить относительные пути в кеше без лишних директорий.

Потенциальные ошибки и подводные камни

  • Если указанный файл не существует в директории, сервис-воркер будет возвращать ошибку при обращении к URL с /.
  • Для проектов с динамической генерацией контента (например, Node.js с Express) directoryIndex не заменяет серверную маршрутизацию, а только влияет на кеширование статических файлов.
  • Использование пустого значения ('') подходит для проектов, где все маршруты явно указаны, иначе страницы могут не кэшироваться корректно.

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

  • Для классических веб-сайтов использовать 'index.html' — стандартный вариант.
  • Для SPA указать 'index.html' и сочетать с navigateFallback для корректной работы всех маршрутов.
  • Проверять наличие индексных файлов в каждой директории, чтобы избежать ошибок при кешировании.

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

var swPrecache = require('sw-precache');

swPrecache.write('service-worker.js', {
  staticFileGlobs: [
    'public/**/*.html',
    'public/**/*.js',
    'public/**/*.css',
    'public/images/**/*.{png,jpg,gif,svg}'
  ],
  stripPrefix: 'public/',
  directoryIndex: 'index.html',
  navigateFallback: '/index.html',
  runtimeCaching: [{
    urlPattern: /^https:\/\/api\.example\.com\//,
    handler: 'networkFirst'
  }]
});

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

  • Все HTML-файлы будут кешироваться с учётом directoryIndex.
  • URL с / автоматически будут перенаправляться на index.html.
  • Динамические API-запросы обрабатываются отдельно через runtimeCaching.

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

Оглавление