Ошибка manifest начинается не с иконки, а с первого этапа, который браузер не прошёл. Сначала убедитесь, что HTML действительно содержит `link rel="manifest"`, запрос возвращает 200 без перехода на login или HTML-страницу, а тело разбирается как JSON. Только после этого исправляйте `start_url`, `scope` и набор icons.

Откройте Chrome DevTools → Application → Manifest. Панель показывает обработанные значения и предупреждения, а Network — реальный URL, Content-Type, редиректы и ответ. Если правка не появилась, включите Disable cache при открытом DevTools и запросите файл снова; переименование URL manifest или иконки помогает отделить кеш от ошибки содержимого.

Первый разрез: файл не загружен или не разобран

СимптомГраница сбояСледующий шаг
Manifest не найденHTML не связал документ с manifestПроверить link, base URL и страницу, с которой тестируется установка
404 или redirectСерверный маршрутОткрыть конечный URL и убрать авторизацию для публичного manifest
Unexpected token <Вместо JSON пришёл HTMLПосмотреть Response и правила fallback роутера
Поле игнорируетсяТип или значение не соответствует алгоритму обработкиСверить регистр, тип и допустимые значения со спецификацией
Иконка сломанаОтдельный ресурс icons.srcПроверить URL, MIME, реальные размеры и прозрачность

W3C регистрирует для manifest тип `application/manifest+json`. Браузеры нередко принимают и JSON-тип, но сервер всё равно должен отдавать JSON, а не универсальный HTML fallback. Не проверяйте файл только командой сборщика: важен ответ по production URL с его заголовками и редиректами.

Минимальный manifest должен быть предсказуемым

{
  "id": "/app/",
  "name": "Example Workspace",
  "short_name": "Workspace",
  "start_url": "/app/",
  "scope": "/app/",
  "display": "standalone",
  "icons": [
    { "src": "/icons/app-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/app-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Это пример для приложения под `/app/`, а не обязательный набор для каждого продукта. По спецификации корневые members формально необязательны, но браузер может требовать часть из них для установки. Поэтому разделяйте ошибку соответствия формату и требования конкретной install surface.

start_url и scope сравниваются после разрешения URL

Относительные URL вычисляются относительно URL самого manifest. После этого браузер проверяет origin и область scope. Если `start_url` выходит за scope, результат может быть отброшен или заменён значением по умолчанию. Сначала выпишите абсолютные итоговые URL, затем сравните origin, path и завершающий slash.

Поле `id` задаёт идентичность приложения и тоже разрешается как URL. Не меняйте его случайно вместе с параметрами аналитики: браузер может воспринять сборку как другое приложение. Для маршрута с авторизацией выберите стартовую страницу, которая корректно показывает login, но не отправляет manifest и icons на закрытый endpoint.

Иконку проверяйте как отдельный HTTP-ресурс

  • Откройте каждый icons.src напрямую и убедитесь в статусе 200.
  • Сравните фактическую ширину и высоту файла со значением sizes.
  • Проверьте type и заголовок ответа, а не только расширение имени.
  • Не используйте HTML-заглушку CDN вместо отсутствующего изображения.
  • При замене файла смените URL или настройте понятную политику кеширования.

Предупреждение про maskable icon и ошибка загрузки обычной иконки имеют разные последствия. Сначала добейтесь доступности базовых ресурсов, затем добавляйте purpose и дополнительные варианты. Автоматически растянутая маленькая картинка может пройти часть проверок, но будет выглядеть размыто на install surface.

Финальный тест проводится как новый пользователь

Очистите данные сайта в тестовом профиле или используйте новый профиль браузера, загрузите страницу по HTTPS и снова откройте Application → Manifest. Проверьте обработанные поля, иконку, start URL и запуск установленного приложения. Service worker диагностируйте отдельно: корректный manifest не доказывает, что офлайн-кеш и lifecycle worker работают.

Для передачи ошибки хватит URL страницы, URL manifest, response headers, текста первого предупреждения и двух вычисленных значений — start_url и scope. Cookie, данные пользователя и полный архив профиля браузера не требуются.

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