Ошибка 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, данные пользователя и полный архив профиля браузера не требуются.