Если приложение уже устанавливается, не начинайте со service worker. Сравните четыре вещи: исходный PNG, превью в DevTools, иконку в диалоге установки и результат на launcher. Первый этап, где картинка испортилась, отделяет неверный файл от маски платформы или кеша установленного приложения.
Manifest хранит набор кандидатов, а браузер выбирает подходящий для конкретной поверхности. `sizes` — подсказка о реальном размере ресурса, а `purpose` сообщает, можно ли применять маску. Один и тот же файл не всегда хорошо выглядит и как обычная, и как maskable-иконка.
Проверка начинается с ответов сервера
| Проверка | Норма | Типичный дефект |
|---|---|---|
| URL icon | HTTP 200 без redirect loop | старый CDN-путь |
| Content-Type | image/png или заявленный формат | text/html ошибки |
| реальные пиксели | совпадают с sizes | 512 указан, файл 192 |
| форма | квадрат | неожиданное кадрирование |
| альфа-канал | по назначению purpose | белая подложка платформы |
Не доверяйте имени `icon-512.png`: откройте файл и измерьте пиксели. Если сервер вместо отсутствующей картинки возвращает HTML-страницу с кодом 200, manifest формально содержит URL, но декодировать иконку браузер не сможет.
Any и maskable решают разные задачи
{
"icons": [
{"src": "/icons/app-192.v4.png", "sizes": "192x192", "type": "image/png", "purpose": "any"},
{"src": "/icons/app-512.v4.png", "sizes": "512x512", "type": "image/png", "purpose": "any"},
{"src": "/icons/maskable-512.v4.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable"}
]
}W3C определяет безопасную область maskable-иконки как центральный круг радиусом 40% от размера. Важные детали должны оставаться внутри него. Платформа вправе обрезать внешнюю часть маской и добавить собственное оформление.
Белый круг чаще связан с прозрачностью
Обычная `any`-иконка может иметь прозрачные поля, похожие на favicon. Для maskable нужен продуманный непрозрачный фон и запас по краям: если пометить прозрачный logo-файл как maskable, пользовательский агент может скомпоновать его на сплошной цвет, а знак станет слишком маленьким или получит белую подложку.
- Экспортировать any и maskable как разные файлы.
- Проверить safe zone в DevTools и на нескольких формах маски.
- Не помещать текст и тонкую рамку у самого края.
- Смотреть и светлый, и тёмный фон launcher.
- Сохранить raster fallback, даже если добавлена SVG-иконка.
Размер кандидата влияет на резкость
Chrome рекомендует для manifest как минимум 192×192 и 512×512. Другие поверхности и браузеры могут выбирать иначе, поэтому набор определяет ваша матрица платформ. Не растягивайте маленький растр до 512: перерисуйте или экспортируйте его из векторного исходника, затем визуально сравните результат после реального масштабирования.
Старая иконка может принадлежать установке
| Где новая | Где старая | Вывод |
|---|---|---|
| URL и DevTools | launcher | кеш/цикл обновления установленной PWA |
| manifest | прямой URL | CDN или deploy не обновлён |
| диалог установки | старая установка | проверить update/reinstall в тесте |
| нигде | везде | не тот manifest или scope страницы |
В актуальной модели Chrome icon и name считаются чувствительными обновлениями. В Chrome 144 изменение содержимого по неизменному полю `icons` не обязано вызывать новую загрузку; для обновления меняют URL или metadata и учитывают подтверждение пользователя. Не советуйте массово очищать все данные сайта: сначала тестируйте на отдельном профиле или устройстве.
Матрица устройства важнее одного preview
- Проверить manifest и assets в DevTools без ошибок.
- Установить чистую сборку на desktop Chromium.
- Проверить taskbar/launcher и переключатель окон.
- Установить на Android и сравнить несколько форм adaptive mask.
- Обновить URL иконки и пройти поддерживаемый update flow.
- Зафиксировать браузер, ОС, версию manifest и скриншоты.
Для разбора подготовьте manifest URL, сами изображения, их фактические размеры и Content-Type, версию браузера/ОС и снимок каждой поверхности. Удалённый доступ к устройству и пользовательский профиль обычно не нужны: проблему воспроизводит чистая тестовая установка.