Руководство по переходу с v5 на v6

MapLibre GL JS v6 поставляется только в виде ES-модулей. UMD-сборка, отдельная сборка CSP и точка входа CommonJS (require('maplibre-gl')) из v5 больше не поддерживаются. Теперь файл сборки называется maplibre-gl.mjs (и maplibre-gl-worker.mjs). Если ваши инструменты сборки или тестовый раннер всё ещё используют require() (обычные скрипты Node.js, тестовые раннеры, которые не преобразуют ESM, серверный код, импортирующий пакет без сборщика), это приводит к ошибке ERR_PACKAGE_PATH_NOT_EXPORTED.

Импорт

Если вы импортируете maplibre-gl из npm с помощью именованных импортов (import {Map} from 'maplibre-gl'), ваши импорты продолжат работать: v6 автоматически разрешает импорт в ESM-сборку.

Если вы использовали импорт по умолчанию (import maplibregl from 'maplibre-gl'), замените его именованными импортами или импортом пространства имён:

// before
import maplibregl from 'maplibre-gl';

// after
import * as maplibregl from 'maplibre-gl';
// or pull in just what you need
import {Map, setWorkerUrl} from 'maplibre-gl';

Тег <script>

Если вы загружаете maplibre-gl через <script src>, используйте вместо этого модульный скрипт:

<!-- before -->
<script src="https://unpkg.com/maplibre-gl@^5/dist/maplibre-gl.js"></script>

<!-- after -->
<script type="module">
    import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.mjs';
</script>

Укажите явную основную версию (например, ^6.0.0), а не @latest или спецификатор без версии. Начиная с v6, страница, закреплённая за @latest, покажет пустой серый экран, а в консоли появится ошибка 404.

setWorkerUrl() предназначен только для сборщиков

При использовании ESM напрямую в браузере (загрузка с CDN, например unpkg, через тег <script type="module">) URL-адрес воркера автоматически определяется по import.meta.url и при необходимости преобразуется в Blob URL того же источника, поэтому вызов setWorkerUrl() не требуется.

При использовании сборщиков (Vite, webpack, esbuild, rspack, Rollup) import.meta.url не может надёжно разрешиться в файл воркера внутри графа модулей сборщика, поэтому каждому потребителю по-прежнему требуется однократный вызов setWorkerUrl(). Примеры для разных сборщиков см. в разделе Установка.

Директивы CSP

Специальная сборка CSP из v5 больше не требуется.

Если вы загружаете MapLibre с CDN, расположенного не на том же источнике, что и ваша страница (например, unpkg), воркер создаётся из Blob URL того же источника, поэтому в CSP необходимо разрешить blob: в worker-src:

worker-src 'self' blob: ;
img-src data: blob: 'self' ;

Если вы размещаете файл воркера самостоятельно (при любой конфигурации сборщика), URL-адрес воркера будет относиться к тому же источнику, и blob: не требуется:

worker-src 'self' ;
img-src data: blob: 'self' ;

zoomLevelsToOverscale

В версии 5 был добавлен экспериментальный параметр, позволяющий нарезать векторные тайлы вместо их масштабирования сверх исходного уровня. Мы протестировали его и обнаружили, что он устраняет многие проблемы, например связанные с отображением подписей. Он меняет отрисовку и результаты вызова queryRenderedFeatures. Чтобы вернуться к прежнему поведению, можно задать zoomLevelsToOverscale: undefined при инициализации карты.

Вложенные свойства GeoJSON

Вложенные объекты и массивы в свойствах объектов GeoJSON теперь сохраняются: объекты, возвращаемые событиями и queryRenderedFeatures, содержат их как настоящие объекты, а не строки JSON. Если для таких свойств вы вызывали JSON.parse, удалите этот вызов — теперь он приводит к ошибке SyntaxError: "[object Object]" is not valid JSON.

-const info = JSON.parse(e.features[0].properties.info);
+const info = e.features[0].properties.info;

pragma mapbox

Если вы использовали #pragma mapbox в общем коде, замените его на #pragma maplibre.

-#pragma mapbox
+#pragma maplibre

События

Теперь все события являются классами. Рекомендуется не использовать instanceof, а проверять поле type. Поскольку типы были заменены классами, в большинстве кодовых баз это не должно вызвать проблем.

styleimagemissing

В v6 обработчики styleimagemissing больше не могут разрешить текущий запрос изображения с помощью вызова Map#addImage. Чтобы перенести обработчик, предоставляющий отсутствующие изображения, замените его на Map#setMissingStyleImageResolver:

-map.on('styleimagemissing', ({id}) => {
+map.setMissingStyleImageResolver((id) => {
     map.addImage(id, generateImage(id));
 });

Обработчик разрешения может быть синхронным или асинхронным. При асинхронной загрузке вызовите Map#addImage до завершения промиса обработчика. Событие styleimagemissing по-прежнему можно использовать для отслеживания изображений, которые так и не удалось разрешить.

Теперь требуется WebGL2

Поддержка WebGL1 удалена; теперь требуется WebGL2. Браузер или устройство, не поддерживающее WebGL2, не сможет отобразить карту в v6. Если WebGL2 недоступен, конструктор Map выбрасывает GPUInitializationError (проверить поддержку можно с помощью instanceof GPUInitializationError, экспортируемого из maplibre-gl), а не возвращает карту.

map.transform удалён

Внутреннее свойство map.transform удалено; теперь Map не расширяет Camera, а объединяет его. Используйте публичный API Map вместо обращения к внутренним деталям transform. Если вы полагались на возможности, предоставляемые transform, которые не охвачены публичным API, создайте issue или PR.