Запись `127.0.0.1 app.local.test` решает DNS, но не создаёт secure context. Поэтому production Service Worker работает по HTTPS, `http://localhost` часто работает как специальное локальное исключение, а произвольный HTTP-поддомен падает с `SecurityError` или вообще не получает доступ к нужному API.
Не включайте браузерный флаг как командное решение. Сначала выведите `window.isSecureContext` и `location.origin`. Если контекст недоверенный, исправляйте схему/сертификат; если доверенный — переходите к origin, MIME, scope и lifecycle.
Четыре похожих сбоя имеют разные причины
| Проверка | Ожидается | Если не так |
|---|---|---|
| isSecureContext | true | HTTPS или допустимый localhost origin |
| scriptURL origin | тот же scheme/host/port | перенести sw.js на origin приложения |
| HTTP response | 200 JavaScript без redirect/HTML | исправить dev proxy и fallback |
| scope | покрывает URL страницы | переместить script или задать допустимый scope |
| controller | не null после навигации/claim | разобрать install/activate lifecycle |
Снимок среды делается одной командой в Console
console.table({
href: location.href,
origin: location.origin,
secure: window.isSecureContext,
serviceWorkerAPI: 'serviceWorker' in navigator,
controller: navigator.serviceWorker?.controller?.scriptURL ?? null
});
navigator.serviceWorker.getRegistrations().then(items =>
console.table(items.map(r => ({scope: r.scope, active: r.active?.scriptURL})))
);Вывод не меняет регистрации. Он отвечает на два первых вопроса: доступен ли API и контролирует ли текущую страницу активный worker. Затем в DevTools → Application → Service Workers смотрят install/activate error, script URL, scope и update state; в Network открывают ответ самого `sw.js`.
У .localhost есть узкое специальное правило
Secure Contexts считает HTTPS и loopback origins потенциально доверенными. Для имён `localhost` и оканчивающихся на `.localhost` браузер может применить исключение, только если соблюдает правила, не позволяющие такому имени уйти на внешний адрес. Произвольные `app.local`, `app.test` и корпоративные зоны в это условие не входят.
- Для одного браузера удобно `http://app.localhost`, если целевые браузеры одинаково поддерживают правило.
- Для команды, мобильного устройства и WebView используйте HTTPS и доверенный локальный CA.
- Сертификат должен покрывать точный hostname в SAN; предупреждение безопасности обходить нельзя.
- Scheme, host и port образуют origin: `https://app.localhost:8443` не равен порту 443.
- Worker одного origin не управляет страницей соседнего поддомена.
Путь sw.js ограничивает максимальный scope
// /sw.js может контролировать весь origin
navigator.serviceWorker.register('/sw.js', { scope: '/' });
// /assets/sw.js по умолчанию получает scope /assets/
// Для scope / сервер должен явно вернуть:
Service-Worker-Allowed: /Спецификация ограничивает максимальный scope родительским путём скрипта. Заголовок `Service-Worker-Allowed` может расширить path boundary, но не меняет origin и не делает HTTP безопасным. Размещать worker в корне проще, если он действительно должен контролировать всё приложение.
Dev proxy часто отдаёт HTML вместо JavaScript
SPA fallback может превратить запрос `/sw.js` в `index.html` со статусом 200. В браузере это выглядит как ошибка MIME или синтаксиса. Откройте script URL напрямую, проверьте Content-Type, отсутствие redirect на login и тело ответа. Service Worker script не должен зависеть от cookie-сессии разработчика.
| Network result | Причина | Исправление |
|---|---|---|
| 301/302 на другой host | canonical redirect | отдельное правило для sw.js |
| 200 text/html | SPA fallback | статический маршрут раньше fallback |
| 401/403 | защищённый asset | публичная выдача versioned script |
| 404 | не тот public root | сверить путь сборки и register |
| 200 JS, install failed | ошибка кода/import | Console и install event |
Старую регистрацию удаляют только как часть теста
Смена hostname создаёт другой origin и другое хранилище регистраций/cache. Очистка данных на `localhost` не очищает `app.localhost`. Перед удалением сначала запишите текущие registrations и cache names; затем удалите только origin тестовой среды и перезагрузите страницу. Массовое очищение браузера скрывает причину и стирает полезное сравнение.
Контрольный прогон отличает регистрацию от управления
- Открыть локальный URL без предупреждений сертификата и подтвердить `isSecureContext === true`.
- Получить `/sw.js` с 200, корректным JavaScript MIME и без redirect.
- Зарегистрировать worker и дождаться activated в Application panel.
- Перезагрузить страницу внутри scope и проверить ненулевой controller.
- Открыть URL вне scope: он не должен случайно обслуживаться worker.
- Изменить версию script, проверить update/activate без бесконечного reload.
- Повторить в чистом профиле и на другом целевом браузере.
Для диагностики сохраните полный local URL, браузер/version, hosts/DNS mapping, SAN сертификата, response headers `/sw.js`, текст ошибки register и список registrations. Приватный ключ локального CA не передавайте. Успех — не просто resolved Promise, а activated worker, который после навигации контролирует только задуманный scope.