Типичные ошибки и чек-лист

Финальный урок собирает самые частые ошибки PWA в одном месте и даёт чек-лист перед релизом.

Большинство проблем с PWA — не экзотика, а несколько повторяющихся ошибок. Зная их, вы сэкономите часы отладки.

Ошибка 1: кеш не обновляется

Самая частая жалоба: «выкатил новую версию, а у пользователей старая». Причины — cache-first без версионирования, новый Service Worker в waiting, агрессивное кеширование sw.js сервером.

Лечение: версионируйте имя кеша, чистите старые кеши на activate, отдавайте sw.js с коротким сроком кеширования, предлагайте пользователю обновление кнопкой.

Ошибка 2: неверный scope Service Worker

«Service Worker зарегистрировался, но запросы не перехватывает». Обычно файл лежит во вложенной папке, и scope не охватывает нужные страницы.

Лечение: кладите sw.js в корень сайта, чтобы scope был /. Проверяйте scope в DevTools → Application → Service Workers.

Ошибка 3: забыли HTTPS

«Локально всё работало, а на проде Service Worker не регистрируется». Часто причина — сайт на проде по HTTP.

Лечение: весь прод — по HTTPS. Локально используйте localhost (там исключение). Проверьте, что нет смешанного контента (часть ресурсов по http).

Ошибка 4: нет офлайн-страницы или не закеширована

«Офлайн показывает уродливую браузерную ошибку». Либо офлайн-страницы нет, либо её забыли положить в кеш.

Лечение: сделайте /offline.html и добавьте её в список кешируемых ассетов на install; отдавайте её как фолбэк для навигаций.

Другие частые промахи

prompt() без клика — диалог установки заблокируется.
Запрос push/уведомлений на входе — массовые отказы, повторно не спросить.
localStorage в Service Worker — его там нет; используйте IndexedDB.
Response без clone() — ошибка «body already used».
Иконки не 192/512 — установка не предлагается.
Кеширование неуспешных ответов — закешированная ошибка вместо контента.

Как работает под капотом отладка

Главный инструмент — DevTools → вкладка Application. Там четыре ключевых раздела: Manifest (как браузер прочитал манифест и что не так), Service Workers (статус, scope, кнопки Update/Unregister, «Update on reload»), Cache Storage (что лежит в кешах) и Storage (общая кнопка «Clear site data» — обнуляет всё для чистого теста). Плюс вкладка Lighthouse для аудита и режим Offline в сетевой панели для проверки офлайна.

Чек-лист перед релизом

[ ] Сайт по HTTPS, нет смешанного контента
[ ] Манифест подключён, валиден, иконки 192 и 512 (+ maskable)
[ ] sw.js в корне, scope = /
[ ] Имя кеша версионируется, старые чистятся на activate
[ ] sw.js не кешируется сервером надолго
[ ] Офлайн-страница есть и закеширована
[ ] Стратегии подобраны по типу ресурса
[ ] Установка предлагается в подходящий момент (и инструкция для iOS)
[ ] Прогнан Lighthouse, замечания закрыты

Итоги

Топ-ошибки: кеш не обновляется, неверный scope, забыли HTTPS, нет офлайн-страницы.
Большинство лечится версионированием кеша, файлом в корне, HTTPS и закешированным /offline.html.
Отлаживайте через DevTools → Application и Lighthouse.
Перед релизом проходите чек-лист — это экономит часы.