Если приложение уже устанавливается, не начинайте со service worker. Сравните четыре вещи: исходный PNG, превью в DevTools, иконку в диалоге установки и результат на launcher. Первый этап, где картинка испортилась, отделяет неверный файл от маски платформы или кеша установленного приложения.

Manifest хранит набор кандидатов, а браузер выбирает подходящий для конкретной поверхности. `sizes` — подсказка о реальном размере ресурса, а `purpose` сообщает, можно ли применять маску. Один и тот же файл не всегда хорошо выглядит и как обычная, и как maskable-иконка.

Проверка начинается с ответов сервера

ПроверкаНормаТипичный дефект
URL iconHTTP 200 без redirect loopстарый CDN-путь
Content-Typeimage/png или заявленный форматtext/html ошибки
реальные пикселисовпадают с sizes512 указан, файл 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 и DevToolslauncherкеш/цикл обновления установленной PWA
manifestпрямой URLCDN или deploy не обновлён
диалог установкистарая установкапроверить update/reinstall в тесте
нигдевездене тот manifest или scope страницы

В актуальной модели Chrome icon и name считаются чувствительными обновлениями. В Chrome 144 изменение содержимого по неизменному полю `icons` не обязано вызывать новую загрузку; для обновления меняют URL или metadata и учитывают подтверждение пользователя. Не советуйте массово очищать все данные сайта: сначала тестируйте на отдельном профиле или устройстве.

Матрица устройства важнее одного preview

  1. Проверить manifest и assets в DevTools без ошибок.
  2. Установить чистую сборку на desktop Chromium.
  3. Проверить taskbar/launcher и переключатель окон.
  4. Установить на Android и сравнить несколько форм adaptive mask.
  5. Обновить URL иконки и пройти поддерживаемый update flow.
  6. Зафиксировать браузер, ОС, версию manifest и скриншоты.

Для разбора подготовьте manifest URL, сами изображения, их фактические размеры и Content-Type, версию браузера/ОС и снимок каждой поверхности. Удалённый доступ к устройству и пользовательский профиль обычно не нужны: проблему воспроизводит чистая тестовая установка.

Проверенные источники