Наличие manifest и установленной иконки еще не означает, что PWA работает офлайн. Без сети приложение зависит от того, контролирует ли страницу service worker, какие ресурсы закешированы и есть ли fallback для навигационных запросов.

Проверяйте офлайн после первого полного посещения и перезагрузки под контролем активного воркера. Разделите оболочку приложения, статические файлы и API: для каждого класса нужна собственная стратегия кеширования и понятное поведение при отсутствии данных.

Что проверить в первую очередь

Сначала зафиксируйте наблюдаемое поведение и не меняйте сразу несколько настроек. Важны точное время сбоя, адрес или сценарий, ожидаемый результат и последнее известное рабочее состояние. Так можно отличить причину от случайного совпадения и сохранить возможность быстрого отката.

  • Убедитесь, что service worker активен и текущая страница отмечена как controlled.
  • Проверьте scope и путь файла воркера относительно маршрутов приложения.
  • Посмотрите Cache Storage и убедитесь, что HTML-оболочка, CSS, JS и нужные иконки реально сохранены.
  • Отключите сеть в DevTools и отдельно проверьте прямой переход на внутренний URL.

Почему возникает проблема

У подобных сбоев редко бывает одна универсальная причина. На итог одновременно влияют конфигурация приложения, окружение, данные, кеш, права и внешние сервисы. Проверка должна идти от внешнего симптома к конкретному уровню, на котором впервые появляется неверное состояние.

  • Воркер зарегистрирован в подкаталоге и не контролирует остальные маршруты.
  • Precache завершился ошибкой из-за одного отсутствующего файла, поэтому кеш не создан полностью.
  • Навигационные запросы уходят только в сеть и не имеют offline fallback.
  • Новая сборка удаляет старый кеш до успешной активации и загрузки новых ресурсов.
  • Интерфейс ожидает API-данные и падает, хотя статическая оболочка доступна.

Пошаговая диагностика

Диагностику проводите на копии или в контролируемое время. Перед изменениями сохраните конфигурацию, данные и журналы. Каждый шаг должен отвечать на один вопрос и оставлять измеримый результат: код ответа, запись в логе, состояние процесса, значение поля или воспроизводимый тест.

  • Проверьте lifecycle install, waiting, activate и сообщения об ошибках в консоли service worker.
  • Откройте список кешей, версии и фактические Request URL с учетом query string.
  • Проверьте ответ fetch handler для document, script, style, image и API отдельно.
  • Выполните hard reload онлайн, обычную перезагрузку и только затем повторите тест офлайн.
  • Проверьте лимит хранилища и сценарий очистки кеша браузером.

Выбор стратегии кеширования

Одна стратегия для всех запросов приводит либо к устаревшим данным, либо к полной неработоспособности без сети.

  • App shell и версионированные статические файлы подходят для precache или cache first.
  • HTML-навигацию можно обслуживать network first с проверенным offline fallback.
  • API с персональными данными не кешируйте без явной модели безопасности и срока жизни.
  • Изображения допускают stale-while-revalidate с лимитом количества и возраста.
  • Операции записи храните в очереди только при идемпотентном серверном API и понятном статусе синхронизации.

Как исправить проблему

Исправление лучше разбить на небольшие обратимые изменения. После каждого шага повторяйте исходный сценарий и проверяйте соседние функции. Если правка касается данных, сначала выполните ее на ограниченной выборке и сохраните журнал затронутых записей.

  • Исправьте scope и заголовок Service-Worker-Allowed, если воркер должен контролировать более широкий путь.
  • Сделайте precache атомарным и обновляйте список ресурсов при каждой сборке.
  • Добавьте navigation fallback, который не перехватывает API и служебные URL.
  • Удаляйте старые кеши только после успешной активации новой версии.
  • Показывайте офлайн-состояние и отсутствие данных вместо бесконечного loader или падения.

Безопасный порядок внедрения

  • Сохраните резервную копию затрагиваемых файлов, базы и конфигурации, а также заранее опишите способ отката.
  • Воспроизведите сбой на тестовой записи, учетной записи или отдельном окружении без реальных платежей и рассылок.
  • Вносите по одному логическому изменению, фиксируя его в системе контроля версий или журнале работ.
  • Не отключайте права, проверку входных данных и защитные механизмы только ради исчезновения сообщения об ошибке.
  • После выкладки контролируйте логи, метрики и ключевой пользовательский сценарий, а не только открытие одной страницы.

Как проверить результат

Успешный разовый тест еще не доказывает исправление. Нужны повторный запуск, крайние случаи и проверка после очистки кеша, перезапуска процесса или новой сессии. Для критичных сценариев полезно сохранить автоматический тест или хотя бы короткий регрессионный чек-лист.

  • Главная и прямой переход на разрешенный внутренний маршрут открываются без сети.
  • После обновления онлайн новая версия работает, а не оставляет смешанные CSS и JS.
  • API-ошибка отображается понятным состоянием и не раскрывает чужие закешированные данные.
  • Повторное подключение восстанавливает запросы без дублей отправленных операций.

Типичные ошибки при исправлении

  • Считать успешную установку PWA доказательством офлайн-работы.
  • Кешировать ответы с авторизацией общим ключом для разных пользователей.
  • Применять cache first к HTML без стратегии обновления и получать вечную старую версию.
  • Удалять все кеши домена, затрагивая другие приложения и открытые вкладки.

Как предотвратить повторение

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

  • Добавьте офлайн-сценарии в e2e-тесты и проверку каждой production-сборки.
  • Версионируйте app shell и контролируйте переход между версиями.
  • Ограничивайте объем runtime cache и обрабатывайте исчерпание квоты.
  • Документируйте, какие функции доступны офлайн, а какие требуют сети.

Что подготовить для разбора

  • Краткое описание ожидаемого и фактического поведения без паролей, токенов и персональных данных.
  • Точное время и последовательность действий, после которых появляется проблема.
  • Версии приложения, окружения и зависимостей, а также перечень последних изменений.
  • Фрагменты журналов с контекстом до и после ошибки; секреты в них необходимо скрыть.
  • Описание уже выполненных проверок и способ безопасно повторить проблему.

Частые вопросы

Почему PWA работает офлайн только после второго открытия?

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

Можно ли кешировать весь API?

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

Когда нужна помощь специалиста

Если PWA устанавливается, но без сети показывает пустой экран или старые данные, я могу разобрать lifecycle воркера, стратегии кеша и API-сценарии, исправить offline fallback и проверить обновление между версиями.