Ключевой уровень отказоустойчивости в Mapbox GL JS начинается до создания карты — с определения возможности работы WebGL и необходимых браузерных API. При отсутствии поддержки WebGL полноценный рендеринг векторных тайлов невозможен, и требуется переключение на альтернативный режим отображения.
Библиотека предоставляет утилиту проверки:
import mapboxgl from "mapbox-gl";
if (!mapboxgl.supported()) {
// переход на альтернативную реализацию карты
}Варианты fallback на этом уровне:
Отдельный аспект — старые устройства с частично поддерживаемым WebGL. В таких случаях важно учитывать деградацию производительности, а не только бинарную совместимость.
Mapbox GL JS использует JSON-описание стиля, где определяются источники данных, слои и ресурсы (sprite, glyphs). Поломка любого из этих компонентов может привести к частичной или полной потере визуализации.
Один из устойчивых подходов — переключение между стилями:
map.on("error", () => {
map.setStyle("mapbox://styles/mapbox/light-v11");
});Типовые сценарии переключения:
Внутри стиля возможна частичная потеря слоёв. Например:
Пример программного удаления проблемных слоёв:
const safeLayers = ["background", "water", "roads"];
safeLayers.forEach(layer => {
if (map.getLayer(layer)) return;
});Mapbox GL JS активно загружает ресурсы по сети: tiles, sprites, glyphs, style JSON. Любой сбой сети требует стратегии повторных попыток и деградации качества.
Базовая схема повторных запросов:
function fetchWithRetry(url, retries = 3, delay = 500) {
return fetch(url).catch(err => {
if (retries === 0) throw err;
return new Promise(resolve =>
setTimeout(() => resolve(fetchWithRetry(url, retries - 1, delay * 2)), delay)
);
});
}Применяется для:
При нестабильных сетях важно избегать лавинообразных повторов запросов. Используется экспоненциальная задержка:
Одним из наиболее гибких механизмов является перехват всех сетевых запросов Mapbox GL JS:
const map = new mapboxgl.Map({
container: "map",
style: "mapbox://styles/custom/style",
transformRequest: (url, resourceType) => {
if (url.includes("tiles")) {
return {
url: url.replace("primary-domain.com", "fallback-domain.com")
};
}
return { url };
}
});Используется для:
Vector sources и raster sources могут иметь разные уровни резервирования.
map.addSource("roads", {
type: "vector",
tiles: [
"https://primary.tiles.com/{z}/{x}/{y}.pbf",
"https://backup.tiles.com/{z}/{x}/{y}.pbf"
],
minzoom: 0,
maxzoom: 14
});Хотя Mapbox GL JS не автоматически балансирует между URL внутри массива в продвинутом режиме, логика может быть реализована через:
Service Worker обеспечивает перехват сетевых запросов и кэширование геоданных.
Основные стратегии:
Пример базовой стратегии кэширования:
self.addEventListener("fetch", event => {
event.respondWith(
caches.match(event.request).then(cached => {
if (cached) return cached;
return fetch(event.request).then(response => {
return caches.open("map-cache").then(cache => {
cache.put(event.request, response.clone());
return response;
});
});
})
);
});Поведение при отсутствии сети:
Sprite (иконки) и glyphs (шрифты) критичны для корректного отображения карты.
map.setStyle({
version: 8,
sprite: [
"https://primary.com/sprite",
"https://backup.com/sprite"
]
});Реализация на практике часто требует:
Шрифты особенно чувствительны к сбоям CDN:
Стратегии:
При ошибках рендеринга WebGL или перегрузке GPU требуется упрощение карты.
map.setLayoutProperty("buildings-3d", "visibility", "none");Иерархия визуализации:
Ошибки авторизации приводят к полной невозможности загрузки тайлов.
Типовые сценарии:
Обработка:
map.on("error", (e) => {
if (e.error && e.error.status === 401) {
map.setStyle("/static/fallback-style.json");
}
});Fallback стиль обычно:
Mapbox GL JS предоставляет события жизненного цикла:
loaderroridledatastyledatamap.on("error", () => {
const canvas = map.getCanvas();
canvas.style.opacity = 0.5;
});Расширенная стратегия:
При полном отказе WebGL возможны альтернативные движки:
Логика переключения:
if (!mapboxgl.supported()) {
initLeafletMap();
}Mapbox GL JS сильно зависит от повторного использования данных.
Типы кэширования:
Эффекты:
Offline режим требует заранее подготовленных данных:
Ограничения:
Структура устойчивости системы отображения:
Каждый уровень активируется при деградации предыдущего, обеспечивая сохранение хотя бы минимальной географической информации даже при множественных отказах инфраструктуры или браузера.