---
title: "MapLibre GL JS"
description: "使用 MapLibre GL JS 将延迟加载、与提供商无关的矢量地图添加到 Nuxt 中。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/scripts/maplibre"
last_updated: "2026-09-23T10:33:09.621Z"
---

[MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) 是一个用于交互式矢量地图的开源 WebGL 渲染器。它负责渲染地图并处理交互；样式、瓦片源、归属信息、地理编码和路径规划服务则由你分别选择。

Nuxt Scripts 通过 [`useScriptMapLibre()`{lang="ts"}](/scripts/maplibre/api/use-script-maplibre) 组合式函数以及用于常见地图资源的声明式组件支持 MapLibre GL JS v6。MapLibre v6 仅支持 ESM，因此 Nuxt Scripts 会从 `maplibre-gl` 包加载它，而不是使用 CDN 脚本标签。样式表也来自同一个包。

::script-types{exclude-components}
::

## 设置

安装 MapLibre v6，然后启用注册表条目：

```bash
pnpm add -D maplibre-gl
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  scripts: {
    registry: {
      maplibre: { trigger: false },
    },
  },
})
```

## 快速开始

传入 MapLibre 样式 URL 或内联样式规范。本示例使用 OpenFreeMap 的免密钥 Liberty 样式。

```vue
<script setup lang="ts">
import type { LngLatLike } from 'maplibre-gl'

const center = ref<LngLatLike>([144.9631, -37.8136])
</script>

<template>
  <ScriptMapLibreMap
    v-model:center="center"
    map-style="https://tiles.openfreemap.org/styles/liberty"
    :zoom="12"
    width="100%"
    :height="480"
    aria-label="墨尔本市中心地图"
  >
    <template #description>
      墨尔本中央商务区的交互式街道地图。
    </template>

    <ScriptMapLibreNavigationControl position="top-right" />

    <ScriptMapLibreMarker
      :position="center"
      aria-label="墨尔本中央商务区"
    >
      <ScriptMapLibrePopup>
        墨尔本中央商务区
      </ScriptMapLibrePopup>
    </ScriptMapLibreMarker>
  </ScriptMapLibreMap>
</template>
```

MapLibre 坐标使用 `[经度, 纬度]` 顺序。这与 Leaflet 使用的 `[纬度, 经度]` 顺序相反。

默认的 `visible` 触发器会将 SDK、样式和地图切片请求延迟到地图接近视口时。该组件会在 SSR 期间预留尺寸，以避免布局偏移。

::callout{color="amber"}
OpenFreeMap 的公共实例无需 API 密钥，但不提供 SLA。在选择生产环境中的样式服务之前，请阅读[样式与提供商](/scripts/maplibre/guides/styles-and-providers)。
::

::callout{icon="i-lucide-route"}
\*\*真实案例：\*\*使用响应式路线进度、实时配送员标记、错误回退内容和无障碍状态替代方案，构建[配送跟踪器](/scripts/maplibre/guides/delivery-tracker)。
::

## 组件

- [`<ScriptMapLibreMap>`{lang="html"}](/scripts/maplibre/api/script-maplibre-map) 创建地图并控制延迟加载。
- [`<ScriptMapLibreMarker>`{lang="html"}](/scripts/maplibre/api/marker) 添加无障碍、响应式标记。
- [`<ScriptMapLibrePopup>`{lang="html"}](/scripts/maplibre/api/popup) 将插槽中的 HTML 绑定到标记或坐标。
- [`<ScriptMapLibreNavigationControl>`{lang="html"}](/scripts/maplibre/api/navigation-control) 添加缩放、罗盘和倾斜控制。
- [`<ScriptMapLibreScaleControl>`{lang="html"}](/scripts/maplibre/api/scale-control) 添加比例尺。
- [`<ScriptMapLibreGeolocateControl>`{lang="html"}](/scripts/maplibre/api/geolocate-control) 查找用户的位置。
- [`<ScriptMapLibreFullscreenControl>`{lang="html"}](/scripts/maplibre/api/fullscreen-control) 切换全屏模式。
- [`<ScriptMapLibreAttributionControl>`{lang="html"}](/scripts/maplibre/api/attribution-control) 移动地图归属信息或更改其样式。
- [`<ScriptMapLibreGeoJson>`{lang="html"}](/scripts/maplibre/api/geojson) 管理 GeoJSON 源及其样式图层，包括[聚类](/scripts/maplibre/api/geojson#clustering)。

## 指南

- [配送跟踪器](/scripts/maplibre/guides/delivery-tracker) 使用响应式标记和样式化 GeoJSON 构建实用的路线跟踪器。
- [样式与提供商](/scripts/maplibre/guides/styles-and-providers) 区分渲染器、样式、瓦片服务和地图数据的选择。
- [性能、CSP 与无障碍](/scripts/maplibre/guides/performance-csp-and-accessibility) 介绍加载触发器、WebGL 回退方案、worker 和装饰性地图。
- [原始地图实例](/scripts/maplibre/guides/raw-map-instance) 介绍图层事件、筛选、要素状态和相机动画移动。

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.