Введение

Используйте запрос ?worker&url в Vite, чтобы получить URL-адрес упакованного автономного воркера:

import {Map, setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';

setWorkerUrl(workerUrl);

const map = new Map({/* … */});

Используйте ?worker&url вместо обычного ?url: воркер из dist импортирует соседний файл maplibre-gl-shared.mjs, а ?url в производственных сборках копирует файл воркера без изменений, не добавляя этот соседний файл — из-за этого при первом импорте воркер завершится с ошибкой, и векторные тайлы не загрузятся. ?worker&url пропускает файл через конвейер обработки воркеров Vite, создавая автономный фрагмент. В режиме разработки работают оба варианта.

Если при сборке используется SSR (TanStack Start, Astro и т. д.) и Vite разрешает точку входа CommonJS на сервере, также добавьте:

export default defineConfig({
    ssr: {noExternal: ['maplibre-gl']}
});

import {Map, setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

setWorkerUrl(new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url).toString());

const map = new Map({/* … */});

В rspack и rsbuild используется тот же подход.

Next.js — исключение, в том числе в режиме next build --webpack. См. вкладку Turbopack.

import * as esbuild from 'esbuild';
import {copyFileSync} from 'fs';

await esbuild.build({
    entryPoints: ['src/main.ts'],
    bundle: true,
    outdir: 'dist',
    format: 'esm'
});

copyFileSync(
    'node_modules/maplibre-gl/dist/maplibre-gl-worker.mjs',
    'dist/maplibre-gl-worker.mjs'
);

import {Map, setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

setWorkerUrl(new URL('./maplibre-gl-worker.mjs', import.meta.url).toString());

const map = new Map({/* … */});

import copy from 'rollup-plugin-copy';

export default {
    plugins: [
        copy({
            targets: [
                {src: 'node_modules/maplibre-gl/dist/maplibre-gl-worker.mjs', dest: 'dist'}
            ]
        }),
        /* ... */
    ]
};

import {Map, setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

setWorkerUrl(new URL('./maplibre-gl-worker.mjs', import.meta.url).toString());

const map = new Map({/* … */});

Turbopack используется в качестве сборщика по умолчанию в Next.js, где вы, скорее всего, с ним и столкнётесь, поэтому приведённые ниже инструкции по настройке предназначены для приложения Next.js.

Turbopack преобразует new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url) в ресурс с хешированным именем, но не помещает рядом с ним соседний файл воркера maplibre-gl-shared.mjs. При первом импорте воркер завершится с ошибкой, и карта отобразится, но не запросит ни одного тайла. Вместо этого разместите оба файла в public/ и укажите воркер в setWorkerUrl:

import {copyFileSync, mkdirSync} from 'node:fs';
import {createRequire} from 'node:module';
import path from 'node:path';

const dist = path.join(path.dirname(createRequire(import.meta.url).resolve('maplibre-gl/package.json')), 'dist');
const dest = path.join(process.cwd(), 'public', 'maplibre');

mkdirSync(dest, {recursive: true});
for (const file of ['maplibre-gl-worker.mjs', 'maplibre-gl-shared.mjs']) {
    copyFileSync(path.join(dist, file), path.join(dest, file));
}

{
    "scripts": {
        "prebuild": "node ./scripts/copy-maplibre-worker.mjs",
        "predev": "node ./scripts/copy-maplibre-worker.mjs"
    }
}

'use client';

import {Map, setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

setWorkerUrl('/maplibre/maplibre-gl-worker.mjs');

const map = new Map({/* … */});

Скрипт копирует оба файла, а не только воркер. Это необходимо, поскольку воркер импортирует maplibre-gl-shared.mjs по относительному пути, поэтому оба файла должны находиться в одном каталоге.

Копирование выполняется во время сборки из node_modules, поэтому используемая версия всегда соответствует установленной. Префиксы жизненного цикла npm соответствуют точному имени скрипта, поэтому prebuild и predev выполняются перед build и dev, но не перед пользовательским скриптом, например build:local. При необходимости добавьте для таких скриптов соответствующий хук pre. Одного postinstall недостаточно, поскольку менеджеры пакетов пропускают скрипты жизненного цикла, если во время установки ничего не требуется делать, а --ignore-scripts полностью их пропускает.

Это необходимо для обоих режимов сборщика Next.js: next build (Turbopack) и next build --webpack, поскольку описанная выше обработка ресурсов выполняется средствами Next.js, а не только Turbopack.

Загрузите MapLibre напрямую с UNPKG в виде ES-модуля с помощью тега <script type="module">. Инструкции по выбору конкретных версий и диапазонов semver см. на сайте unpkg.com.

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@^6.9.0/dist/maplibre-gl.css" />
<div id="map" style="height: 400px"></div>
<script type="module">
    import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.9.0/dist/maplibre-gl.mjs';

    const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [0, 0],
        zoom: 1
    });
</script>

Воркер автоматически определяется по URL-адресу импортированного модуля и загружается через Blob URL того же источника, поэтому загрузка с CDN другого источника работает без дополнительной настройки.

Если строгая политика CSP запрещает blob: в worker-src, явно укажите URL-адрес воркера, размещённого на том же источнике:

maplibregl.setWorkerUrl('/path/to/maplibre-gl-worker.mjs');

Рабочий пример см. в разделе Отображение карты.