Сервис-воркер добавляется за час: манифест, файл воркера, регистрация. Сайт становится устанавливаемым, работает без сети, открывается с рабочего стола как приложение.
А потом вы выкладываете обновление, и часть пользователей его не видит. Не «через час увидит» — не видит вообще, потому что весь их интерфейс отдаётся из кэша, установленного месяц назад. Вы просите очистить кэш браузера; это не помогает, потому что кэш воркера — отдельное хранилище. Вы правите код и выкладываете ещё раз; тоже не помогает, по той же причине.
Эта статья про то, как устроить версионирование так, чтобы описанное выше стало невозможным.
#Что понадобится
- HTTPS. Без него сервис-воркер не регистрируется вовсе — исключение только для локального адреса при разработке.
- Версия сборки, доступная и серверу, и шаблонам. Это ключевая деталь всей схемы.
- Понимание, какие ответы можно кэшировать надолго, а какие нельзя никогда.
- Работающая выкладка с проверкой версии — иначе кэш воркера просто добавит ещё один слой, на котором обновление может застрять. Общий маршрут — в статье о том, как поднять свой ИИ-сервис.
#Шаг 1. Привязать имя кэша к версии сборки
Единственное правило, из которого следует всё остальное:
имя кэша содержит версию сборки, и оно меняется при каждом выпуске.
const CACHE_VERSION = 'persona-v2.34.0'; // синхронно с версией приложения
Строка выглядит незначительной, но именно она превращает обновление кэша из ручной операции в автоматическую. Новое имя кэша — это новое хранилище, старое удаляется на этапе активации:
self.addEventListener('activate', (event) => {
event.waitUntil(
caches.keys()
.then((keys) => Promise.all(
keys.filter((k) => k !== CACHE_VERSION).map((k) => caches.delete(k))
))
.then(() => self.clients.claim())
);
});
Дисциплина, без которой схема разваливается: версия в файле воркера поднимается в том же коммите, что и версия приложения. Забыли — пользователи получают новый код с чужой статикой, и это худший из возможных вариантов: не «старая версия», а несогласованная смесь двух.
#Шаг 2. Написать минимальный воркер
const CACHE_VERSION = 'persona-v2.34.0';
const PRECACHE = ['/static/css/app.css', '/static/js/app.js', '/static/manifest.json'];
self.addEventListener('install', (event) => {
event.waitUntil(
caches.open(CACHE_VERSION)
.then((cache) => Promise.all(
// по одному с перехватом: один 404 не должен провалить всю установку
PRECACHE.map((url) => cache.add(url).catch(() => null))
))
.then(() => self.skipWaiting())
);
});
async function networkFirst(request) {
const cache = await caches.open(CACHE_VERSION);
try {
const response = await fetch(request);
if (request.method === 'GET' && response && response.status === 200) {
cache.put(request, response.clone()).catch(() => {});
}
return response;
} catch (err) {
const cached = await cache.match(request);
if (cached) return cached;
throw err;
}
}
async function cacheFirst(request) {
const cache = await caches.open(CACHE_VERSION);
const cached = await cache.match(request);
if (cached) return cached;
const response = await fetch(request);
if (request.method === 'GET' && response && response.status === 200) {
cache.put(request, response.clone()).catch(() => {});
}
return response;
}
self.addEventListener('fetch', (event) => {
const request = event.request;
if (request.method !== 'GET') return;
let url;
try { url = new URL(request.url); } catch (e) { return; }
if (url.protocol !== 'http:' && url.protocol !== 'https:') return;
// Статика версионирована в самом адресе → можно из кэша сразу.
if (url.pathname.startsWith('/static/')) {
event.respondWith(cacheFirst(request));
return;
}
// Всё остальное, включая API и навигации, — сначала сеть.
event.respondWith(networkFirst(request));
});
Три решения, которые стоит понимать.
Установка с перехватом на каждом файле. Один недоступный адрес в списке предварительного кэширования проваливает всю установку воркера, если использовать групповое добавление. Итог — воркер не установился, а вы этого не заметили.
Сначала сеть для навигаций и API. Иначе пользователь получает вчерашние данные и вчерашнюю страницу. Кэш здесь — резерв на случай отсутствия сети, а не основной источник.
Сначала кэш для статики. Это безопасно только если адрес статики содержит версию. Без этого вы кэшируете app.css навечно и получаете ровно ту проблему, ради которой всё затевалось.
#Шаг 3. Версионировать адреса статики
Вторая половина схемы, без которой первая не работает:
/static/css/app.css?v=2.34.0
Параметр подставляется шаблоном из той же версии приложения. Новый выпуск — новый адрес — новая запись в кэше — старая уходит вместе со старым кэшем.
Побочная польза, которая оказалась важнее ожидаемого: этот параметр виден в HTML и годится как проверка при выкладке. У нас деплой не считается успешным, пока не сойдутся две независимые проверки: версия, которую отдаёт ручка живости (то есть версия процесса, реально слушающего порт), и параметр ?v= в HTML (то есть то, что уедет в браузер). Первая ловит осиротевший процесс со старым кодом, вторая — рассинхронизацию кода и статики. Куда это встраивается — в статье про мониторинг личного сервиса.
#Шаг 4. Решить, когда обновлять принудительно
skipWaiting() в примере выше означает: новый воркер активируется немедленно, не дожидаясь закрытия всех вкладок. Это не бесплатно.
| Подход | Плюс | Минус |
|---|---|---|
skipWaiting сразу |
обновление доезжает мгновенно | вкладка может остаться со смесью старых и новых ресурсов |
| Ждать закрытия вкладок | согласованное состояние | обновление доезжает через дни |
| Спросить пользователя | и то и другое | нужен интерфейс уведомления |
Для приложения, которое обновляется часто, а страницы у пользователя живут долго, третий вариант правильнее: воркер сообщает странице, что готово обновление, страница показывает ненавязчивое предложение перезагрузиться. Для личного сервиса на одного-двух человек достаточно первого.
#Проверка результата
1. Инструменты разработчика → Application → Service Workers:
статус activated, версия та, что вы выложили.
2. Application → Cache Storage: ОДНО хранилище с текущей версией.
Два и больше — активация не удалила старое.
3. Отключить сеть → перезагрузить: оболочка приложения открывается.
4. Выложить новую версию, обновить страницу дважды:
во второй раз должна быть новая версия.
Пункт 2 — главный. Накопление хранилищ означает, что удаление старых не отрабатывает, и рано или поздно пользователь получит ресурс из прошлогоднего кэша.
Пункт 4 проверяйте в обычном окне, а не в приватном: в приватном сервис-воркер ведёт себя иначе, и вы проверите не то.
#Что может пойти не так
Пользователь видит старую версию, а у вас всё новое. Классика. Проверьте: поднялась ли версия в файле воркера; версионированы ли адреса статики; удаляются ли старые хранилища при активации. Провал обычно в первом.
Воркер закэшировал ответ API. Приложение показывает данные, которых уже нет. Для API — только «сначала сеть», и никогда не кэшируйте ответы на запросы, изменяющие данные.
Воркер закэшировал редирект или страницу ошибки. Кладите в кэш только успешные ответы, и только собственного происхождения.
После включения политики безопасности сломались шрифты и внешние скрипты. Вы повесили политику на файл воркера. Он ходит за ресурсами сам, и документная политика начинает управлять его запросами. Политика ставится только на HTML-ответы — подробности в статье про Content Security Policy.
Приложение не предлагает установку. Требования к устанавливаемости у браузеров различаются и меняются; на момент написания общий минимум — HTTPS, корректный манифест с иконками и зарегистрированный воркер. Точные условия смотрите в текущей документации вашего браузера.
Воркер невозможно снять. Он не исчезает при обновлении страницы. Пока идёт отладка, снимайте его через инструменты разработчика и держите под рукой аварийный вариант: воркер, который удаляет все хранилища и отменяет собственную регистрацию.
#Частые вопросы
#Нужен ли сервис-воркер, если офлайн-режим не нужен?
Он полезен и без офлайна: заметно ускоряет повторные загрузки за счёт статики из кэша и делает сайт устанавливаемым. Но если вы не готовы поддерживать дисциплину версионирования — лучше не ставить вовсе, чем ставить и раздавать пользователям устаревший интерфейс.
#Заменяет ли установленное веб-приложение настольное?
Отчасти. Отдельное окно, иконка, ярлык — да. Фоновая работа при закрытом окне, доступ к экрану, к микрофону без разрешения, автозапуск — нет. Поэтому у Persona захват работает только в нативной установке; порядок — в гайде про установку Persona на Windows.
#Как обновить воркер у пользователя прямо сейчас?
Никак напрямую: браузер проверяет файл воркера при навигации и периодически. Ускорить можно вызовом обновления из страницы, а гарантированно — только через skipWaiting в новой версии воркера. Если предыдущая версия его не содержала, обновление придёт в срок браузера.
#Что делать со списком предварительного кэширования, если файлов много?
Держите в нём только оболочку приложения — то, без чего не отрисуется первый экран. Остальное попадёт в кэш само при первом обращении. Длинный список удлиняет установку и повышает шанс, что один недоступный адрес всё сломает.
#Помогает ли сервис-воркер с медленным первым открытием?
Нет: при первом визите его ещё нет. Он ускоряет повторные открытия. Первое открытие — это отдельная работа, разобранная в гайде про холодный старт приложения, и там же объясняется, почему в интерфейсе без сборки первым делом стоит убирать генерацию стилей в браузере — про сам подход в статье про HTMX и Alpine без сборки.