Подключение через CDN

MapLibre GL JS может быть подключена напрямую через CDN без сборщиков, настройки npm-пакетов и конфигурации бандлеров. Такой способ используется в прототипах, учебных проектах, административных панелях и любых сценариях, где требуется быстрый старт с минимальной инфраструктурой.

CDN-подключение предполагает загрузку готовых файлов библиотеки и стилей через <script> и <link> теги. В этом случае браузер получает уже собранную UMD-версию библиотеки, готовую к использованию через глобальный объект maplibregl.

Подключение стилей и скрипта

MapLibre GL JS требует двух обязательных ресурсов:

  • JavaScript-библиотека
  • CSS-стили для корректного отображения карты

Сначала подключается CSS, затем Jav * aScript:

<link rel="stylesheet" href="CDN_URL/maplibre-gl.css">

<script src="CDN_URL/maplibre-gl.js"></script>

CSS отвечает за базовую визуализацию карты: контейнер, подписи, контролы, атрибуцию. Без него карта может работать, но будет отображаться некорректно.

Создание контейнера карты

Перед инициализацией карты необходимо определить HTML-элемент, в котором она будет отрисована:

<div id="map"></div>

Контейнер обязан иметь заданные размеры, иначе карта не появится:

#map {
  width: 100%;
  height: 500px;
}

Высота критична: при нулевой высоте WebGL-контекст не создаётся визуально, хотя ошибок может не возникать.

Инициализация карты

После подключения ресурсов доступен глобальный объект maplibregl. Через него создаётся экземпляр карты:

const map = new maplibregl.Map({
  container: 'map',
  style: 'STYLE_URL',
  center: [0, 0],
  zoom: 2
});

Ключевые параметры:

  • container — идентификатор DOM-элемента или сам элемент
  • style — JSON-стиль карты (тайлы, слои, источники)
  • center — начальные координаты [longitude, latitude]
  • zoom — уровень масштабирования

Без корректного style карта не отобразит данные, так как именно стиль определяет визуальную модель слоёв и источников.

Использование CDN-провайдеров

На практике применяются несколько популярных CDN-источников. Они предоставляют одинаковые файлы, но отличаются инфраструктурой доставки.

Пример логики подключения:

  • jsDelivr — оптимизирован для глобальной доставки
  • unpkg — ориентирован на npm-пакеты

Подключение через CDN обычно сводится к указанию версии библиотеки:

<link rel="stylesheet" href="CDN_BASE/maplibre-gl/VERSION/maplibre-gl.css">

<script src="CDN_BASE/maplibre-gl/VERSION/maplibre-gl.js"></script>

Использование версии критично: разные версии могут менять API, поведение рендера и структуру стилей.

Версионирование и стабильность

При подключении через CDN важно фиксировать версию, а не использовать «latest». Это связано с тем, что:

  • возможны breaking changes между релизами
  • поведение WebGL-рендера может изменяться
  • стиль может требовать обновлённого формата источников

Рекомендуется всегда указывать конкретный релиз:

<script src="CDN_BASE/maplibre-gl/1.15.2/maplibre-gl.js"></script>

Работа с глобальным объектом

После загрузки библиотеки появляется глобальный объект maplibregl, содержащий:

  • конструктор Map
  • классы управления (NavigationControl, Popup)
  • вспомогательные функции

Пример добавления стандартных контролов:

map.addControl(new maplibregl.NavigationControl());

Контролы подключаются после создания карты и привязываются к её экземпляру.

Подключение маркеров и всплывающих окон

Даже при CDN-подключении доступны все базовые UI-компоненты:

const marker = new maplibregl.Marker()
  .setLngLat([10, 10])
  .addTo(map);
const popup = new maplibregl.Popup()
  .setLngLat([10, 10])
  .setHTML('<div>Точка</div>')
  .addTo(map);

Эти компоненты не требуют дополнительной конфигурации и работают сразу после загрузки библиотеки.

Частые проблемы при подключении через CDN

При работе через CDN чаще всего встречаются следующие ошибки:

1. Отсутствие CSS Карта отображается «сломано» или без базовых стилей.

2. Не задана высота контейнера WebGL-карта не инициализируется визуально.

3. Неверный порядок подключения CSS должен загружаться до JS, иначе возможны артефакты интерфейса.

4. Несовпадение версий Скрипт и стили разных версий приводят к некорректному отображению.

5. Отсутствие style Без валидного style JSON карта не имеет источника данных и остаётся пустой.

Особенности загрузки через CDN в браузере

CDN-подключение означает, что:

  • библиотека загружается синхронно или асинхронно через сеть
  • кэш браузера может повторно использовать файлы
  • отсутствует этап сборки и транспиляции
  • глобальное пространство имён засоряется объектом maplibregl

При этом WebGL-рендерер инициализируется сразу после загрузки скрипта, без дополнительной компиляции.

Базовый минимальный шаблон страницы

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="CDN_URL/maplibre-gl.css">
</head>
<body>

<div id="map"></div>

<script src="CDN_URL/maplibre-gl.js"></script>
<script>
  const map = new maplibregl.Map({
    container: 'map',
    style: 'STYLE_URL',
    center: [0, 0],
    zoom: 2
  });
</script>

</body>
</html>
Оглавление