maptiler

MapTiler — Agent 技能

@maptiler/sdk · 文档 · Cloud 控制台 · GitHub

涵盖 MapTiler 的所有产品领域：Web SDK、框架集成、原生移动 SDK、Cloud REST API、本地部署的 Server / Engine，以及矢量瓦片架构。参考文档位于 references/ 下，并按需加载。请将 references/INDEX.md 用作精选目录。

---

1. 平台覆盖范围与文件前缀约定

在 references/ 中使用以下前缀筛选条件进行 grep / glob 搜索，避免跨平台混淆：

目标平台	文件名前缀
Web（核心 JS SDK）	sdk-js-*, examples-sdk-js-*
Web 框架（React、Svelte、Vue、Angular）	web-libraries-*, examples-react-*, examples-svelte-*, examples-vuejs-*, examples-angular-*
Web 地图引擎（Leaflet、OpenLayers、Cesium、deck.gl）	examples-leaflet-*, examples-openlayers-*, examples-cesium-*, web-libraries-deck-gl*
Android（Kotlin/Java）	mobile-sdks-android-*, examples-android-*
iOS（Swift）	mobile-sdks-ios-*, examples-ios-*
跨平台移动端（Flutter、React Native）	mobile-sdks-flutter-*, mobile-sdks-react-native-*
Cloud REST API	cloud-api-*, cloud-admin-api-*
本地部署基础设施	on-prem-*
矢量瓦片架构	map-resources-schemas-*
MapLibre 样式规范	map-resources-specifications-*

---

2. 通用规则（适用于所有平台）

A. 禁止泄漏变量

查阅 references/versions.md，并在输出前将所有模板占位符（例如 {{site.versions.sdk}}、{{site.url}}）替换为具体版本字符串或绝对路径。任何响应中都不得输出原始的 {{ 或 }}。

B. 样式现代化（v2/v3 → v4）

务必升级旧版地图样式。此规则适用于 Web、移动端、回退 XYZ 图层、service worker 缓存列表以及样式切换逻辑。

旧版	现代替代项	SDK 常量
basic-v2 / streets-v2-light	base-v4	MapStyle.BASE
basic-v2-dark	base-v4-dark	MapStyle.BASE.DARK
streets-v2	streets-v4	MapStyle.STREETS
outdoor-v2	outdoor-v4	MapStyle.OUTDOOR
satellite / satellite-v2	satellite-v4	MapStyle.SATELLITE
hybrid	hybrid-v4	MapStyle.HYBRID
dataviz-dark	dataviz-v4-dark	MapStyle.DATAVIZ.DARK
topo-v2	topo-v4	MapStyle.TOPO

切勿输出已弃用系列中的 URL 或常量：streets-v2、streets-v2-dark/light、basic-v2*、outdoor-v2*、satellite-v2、hybrid-v2、dataviz-dark、topo-v2。

此规则适用于所有提及样式或瓦片路径的场景：

• 移动端样式端点（iOS / Android / Flutter / RN 原始 style.json URL）：https://api.maptiler.com/maps/streets-v4-dark/style.json?key=YOUR_KEY
• 自托管 / 本地部署的回退 XYZ 图层和 service worker 预缓存列表：/tiles/streets-v4/{z}/{x}/{y}.pbf — 绝不可使用 /tiles/streets-v2/
• 样式切换器 UI 状态（深色/浅色切换、滑动图层、昼夜样式切换）：仅在现代 v4 ID 之间切换

C. 固定版本

所有 SDK、CDN 和依赖项版本均列于 references/versions.md。在输出任何 package.json、<script> 标签、Gradle implementation 字符串或 pubspec.yaml 条目之前，请先阅读。

D. 各平台的坐标约定

MapTiler/MapLibre 系列中的每个 API 都使用 [lng, lat] 顺序。与之集成的平台则不然——这种不匹配是最常见的 bug。请在边界处进行转换，不要只在脑中转换。

来源	约定	遇到时机
MapTiler SDK JS / MapLibre / Mapbox	[lng, lat] 数组	所有 Web SDK 代码（中心点、标记、数据源坐标、表达式）
GeoJSON 规范	[lng, lat]（或 [lng, lat, ele]）	每个 geometry.coordinates 值
MapTiler REST URL	路径中使用 {lng},{lat}	/geocoding/{lng},{lat}.json、/elevation/dataset/{lng},{lat}.json、静态地图 /static/{lng},{lat},{zoom}/…
Leaflet	(lat, lng) — 顺序相反	L.map().setView([lat, lng], z)、L.marker([lat, lng])、L.latLng(lat, lng)
iOS CLLocationCoordinate2D	(latitude:, longitude:) — 结构体字段顺序相反	Apple CoreLocation。构建 MapTiler URL 时：c.longitude, c.latitude
Android LatLng / LngLat	MapTiler Android SDK 使用 LngLat(lng, lat)；系统 Location 将 latitude/longitude 作为独立属性公开	以 SDK 类型为准，而非系统类型
MapTiler Geolocation API 响应	独立字段 latitude / longitude（不是成对值）	在传入任何 SDK 调用前，构造 [loc.longitude, loc.latitude]

规则：传入 Leaflet、iOS CoreLocation 或任何具有“独立字段”的响应时，务必显式交换顺序。切勿假设下游库采用与上游 API 相同的约定。

E. API 密钥安全

• 如果用户在消息中粘贴了看起来真实的 API 密钥（类似 UUID 或令牌的字符串，附近有“key”“token”“apikey”等词），请提醒他们：“你在纯文本中分享了一个看起来仍在使用的密钥——测试完成后，请前往 https://cloud.maptiler.com/account/keys/ 轮换该密钥。”在你自己的输出中使用占位符（YOUR_MAPTILER_API_KEY）。
• **服务令牌不得离开后端。**生成调用 service.maptiler.com/v1/… 的示例代码时，请从 process.env / 等效位置读取令牌，绝不要在公开客户端代码片段中嵌入看起来像令牌的占位符。
• 在生产示例中按来源限制密钥。建议在 API 密钥设置中使用 origins: ["*.example.com"]，而不是不受限制的密钥。

---

3. Web — MapTiler SDK JS

为什么使用 MapTiler SDK（而不是原始 MapLibre）

**始终从 @maptiler/sdk 导入，绝不要直接从 maplibre-gl 导入。**该 SDK 重新导出了 MapLibre 的所有内容，并添加了：

• config.apiKey — 设置 API 密钥的统一位置；支持基于会话的计费
• MapStyle 枚举 — 始终保持最新的样式 ID；绝不要硬编码样式 URL
• helpers.* — 一行代码即可创建折线、多边形、点和热力图（支持聚类、色带以及 GPX/KML）
• 内置的 geocoding、geolocation、elevation、staticMaps、coordinates、data、math 模块
• terrain: true — 通过单个构造函数标志启用 3D 地形
• projection: 'globe' — 配备 halo 和 space 大气效果的地球视图
• 构造函数级控件（navigationControl: true、geolocateControl: true，……）
• 扩展了 MapLibre 类型的完整 TypeScript 类型

MapLibre 插件仍保持兼容——该 SDK 的 Map 继承自 MapLibre 的 Map。

安装

npm install @maptiler/sdk

CSS 必须单独导入：

import '@maptiler/sdk/dist/maptiler-sdk.css';

API 密钥

**绝不要硬编码虚假密钥。**请向用户询问，或指引他们前往 https://cloud.maptiler.com/account/keys/。框架的环境变量约定：

工具	环境变量
Vite	VITE_MAPTILER_API_KEY
Next.js	NEXT_PUBLIC_MAPTILER_API_KEY
CRA	REACT_APP_MAPTILER_API_KEY

import * as maptilersdk from '@maptiler/sdk';
maptilersdk.config.apiKey = import.meta.env.VITE_MAPTILER_API_KEY;

最简地图

const map = new maptilersdk.Map({
  container: 'map',                       // element or ID
  style: maptilersdk.MapStyle.STREETS,    // enum — always latest
  center: [14.4178, 50.1167],             // [lng, lat] — NOT [lat, lng]!
  zoom: 12,
});

重要：容器必须设置明确的尺寸（例如 height: 100vh），否则地图将不可见。

构造函数选项（最常用）

new maptilersdk.Map({
  container, style, center, zoom,
  pitch: 0, bearing: 0,            // 0–85 / rotation
  projection: 'mercator',          // or 'globe'
  terrain: false, terrainExaggeration: 1,
  hash: true,                      // sync viewport to URL
  language: maptilersdk.Language.AUTO,
  cooperativeGestures: true,
  geolocate: maptilersdk.GeolocationType.POINT,
  navigationControl: true, geolocateControl: true,
  scaleControl: true, terrainControl: false,
  fullscreenControl: false, projectionControl: false,
  minimap: { containerStyle: { width: '200px', height: '150px' } },  // or `true` for defaults
});

对于 navigationControl、geolocateControl、scaleControl、terrainControl、fullscreenControl、projectionControl、minimap 和 geolocate，优先使用构造函数标志，而不是在初始化后调用 addControl。每项都接受 true、角落字符串（'top-right'）或配置对象。仅在需要第三方插件或在初始化后进行修改时，才使用 addControl(new MaplibreThing(), 'top-right')。

地图样式（完整列表——15 种参考样式）

样式	用途	变体
MapStyle.STREETS	全面的街道地图	.DARK、.PASTEL
MapStyle.SATELLITE	精美的卫星地图	.DARK
MapStyle.HYBRID	带有背景信息的精美卫星地图	.DARK
MapStyle.OUTDOOR	适合徒步和运动的地图	.DARK
MapStyle.WINTER	适合冬季活动的地图	.DARK
MapStyle.TOPO	通用地形图	.DARK、.PASTEL、.TOPOGRAPHIQUE
MapStyle.DATAVIZ	简洁的数据可视化地图	.DARK、.LIGHT
MapStyle.BASE	清晰的通用地图	.DARK、.LIGHT
MapStyle.BRIGHT	用于背景信息或导航的鲜明地图	.DARK、.LIGHT、.PASTEL
MapStyle.BACKDROP	单色背景地图	.DARK、.LIGHT
MapStyle.AQUARELLE	艺术风格水彩地图	.DARK、.VIVID
MapStyle.LANDSCAPE	浅色晕渲地形图	.DARK、.VIVID
MapStyle.OCEAN	海床和水深地图	.DARK
MapStyle.OPENSTREETMAP	丰富且熟悉的 OSM 社区风格	.DARK
MapStyle.TONER	对比鲜明的单色地图	.LITE

请使用基于 Proxy 的常量（MapStyle.STREETS），不要硬编码 URL。如果请求的变体不存在，Proxy 会回退到 .DEFAULT，因此拼写错误会静默显示基础样式，不会产生编译时错误。

权威参考（描述、方法、变体解析规则）：references/sdk-js-map-styles.md。

语言

maptilersdk.config.primaryLanguage = maptilersdk.Language.ENGLISH;
map.setLanguage(maptilersdk.Language.FRENCH);     // runtime switch

特殊值：Language.AUTO（浏览器）、Language.LOCAL、Language.VISITOR。

---

4. Web — 常用配方

// Marker + popup
new maptilersdk.Marker({ color: '#FF0000' })
  .setLngLat([14.4178, 50.1167])
  .setPopup(new maptilersdk.Popup().setHTML('<h3>Prague</h3>'))
  .addTo(map);

// Geocoding (forward / reverse) — features[].geometry.coordinates is [lng, lat]
await maptilersdk.geocoding.forward('Prague', { limit: 5, proximity: [14.4178, 50.1167] });
await maptilersdk.geocoding.reverse([14.4178, 50.1167]);

// Camera animation
map.flyTo({ center: [14.4178, 50.1167], zoom: 15, pitch: 60, duration: 3000 });

// Static map URL
maptilersdk.staticMaps.centered([14.4178, 50.1167], 12,
  { hiDPI: true, width: 800, height: 600, style: maptilersdk.MapStyle.OUTDOOR });

矢量图层辅助函数（helpers.add*）

一行即可创建最常见的图层类型。所有函数都接受相同格式：{ data, beforeId, … }。data 可以是 GeoJSON、URL（GeoJSON / GPX / KML）或 MapTiler 数据集 UUID。

辅助函数	主要选项
addPolyline	lineColor、lineWidth、outline
addPolygon	fillColor、fillOpacity、outlineColor
addPoint	pointColor、pointRadius、cluster、showLabel
addHeatmap	colorRamp（ColorRamp.*）、property、radius、opacity

maptilersdk.helpers.addPoint(map, {
  data: pointsGeoJSON, pointColor: '#FF0000', pointRadius: 8,
  cluster: true, showLabel: true, beforeId: 'waterway-label',
});

3D 地形 / 地球仪——单标志构造函数

// 3D terrain
new maptilersdk.Map({ container: 'map', style: maptilersdk.MapStyle.OUTDOOR,
  terrain: true, terrainExaggeration: 1.5, terrainControl: true, pitch: 60 });

// Globe projection
new maptilersdk.Map({ container: 'map', style: maptilersdk.MapStyle.SATELLITE,
  projection: 'globe', halo: true, space: true, center: [0, 20], zoom: 1.5 });

完整的辅助函数参考和选项类型：references/sdk-js-map.md。可运行的主题示例：搜索 examples-sdk-js-*.md（标记、地理编码、聚类、热力图、地形、地球仪、天气等）。

---

5. Web 框架

React / Next.js

import { useEffect, useRef } from 'react';
import * as maptilersdk from '@maptiler/sdk';
import '@maptiler/sdk/dist/maptiler-sdk.css';

maptilersdk.config.apiKey = import.meta.env.VITE_MAPTILER_API_KEY;

export default function MapComponent() {
  const containerRef = useRef(null);
  const mapRef = useRef(null);

  useEffect(() => {
    if (mapRef.current) return;                              // Strict-Mode guard
    mapRef.current = new maptilersdk.Map({
      container: containerRef.current,
      style: maptilersdk.MapStyle.STREETS,
      center: [14.4178, 50.1167], zoom: 12,
    });
    return () => { mapRef.current?.remove(); mapRef.current = null; };
  }, []);

  return <div ref={containerRef} style={{ width: '100%', height: '400px' }} />;
}

Next.js App Router：添加 "use client";，使用 NEXT_PUBLIC_MAPTILER_API_KEY。对于 SSR 页面：dynamic(() => import('./Map'), { ssr: false })。

Vue / Svelte / Angular

采用与 React 相同的模式：在挂载钩子（onMounted / onMount / ngOnInit）中实例化地图，在卸载钩子（onUnmounted / onDestroy / ngOnDestroy）中调用 map.remove()，且不要根据响应式状态来决定是否创建地图。各框架的完整代码片段：web-libraries-vue.md · web-libraries-svelte.md · web-libraries-angular.md。

框架生命周期规则（重要）

1. WebGL 清理：React useEffect、Vue onMounted/onUnmounted、Angular ngOnInit/ngOnDestroy、Svelte onMount/onDestroy 中的每个地图实例，在销毁时都必须调用 map.remove() 并将其引用设为 null。
2. 地图创建恰好执行一次：初始化钩子的依赖数组中绝不要放入响应式状态——否则每次状态变化都会销毁并重新创建画布，导致中心点、缩放级别和动态对象丢失。
3. 动态更新使用独立钩子，调用 SDK 更新方法（map.setStyle、map.flyTo、map.setLayoutProperty）——绝不重新初始化。
4. 事件处理器中的过期闭包：当 click/draw.create 监听器需要读取当前 React 状态时，将状态存储在 useRef 中（const stateRef = useRef(state); stateRef.current = state;），并通过 stateRef.current 读取。不要将该状态添加到 effect 依赖项中。

完整的生命周期处理：web-libraries-react.md。

---

6. CDN / 单文件 / Playground

使用 versions.md 中固定的版本——绝不要使用 latest 或过时的构建版本。

<script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.0.2/maptiler-sdk.umd.min.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.0.2/maptiler-sdk.css" rel="stylesheet" />

其他常用的固定版本：

• Leaflet 插件：https://cdn.maptiler.com/maptiler-leaflet-maptilersdk/v4.1.0/maptiler-leaflet-maptilersdk.js
• ol-mapbox-style：https://cdn.jsdelivr.net/npm/[email protected]/dist/olms.js
• CesiumJS：1.141.0（脚本 + /Widgets/widgets.css）

浏览器 ESM：使用 <script type="module"> 或导入映射时，必须指定 .mjs 构建版本（maptiler-sdk.mjs），而不是 UMD 构建版本——从 UMD 导入具名 ES 模块会触发控制台错误。

---

7. 矢量图层、架构与数据驱动样式

架构验证（必需）

在编写任何样式规则、筛选条件或绘制／布局表达式之前，先确定瓦片集来源并查阅其架构参考。切勿臆造 source-layer ID、要素属性键（class、subclass、ele、height 等）或绘制字段。

OMT → Planet v4 迁移陷阱。 较旧的 OpenMapTiles 架构将所有道路、铁路、航空和渡轮要素合并到一个 transportation 图层中。Planet v4 将它们拆分为独立的顶层图层——road、railway、aviation、aviation_line、ferry、aerialway。如果你正在迁移 Mapbox/MapLibre 样式，或参考 2024 年之前的教程，图层名 transportation 将无法解析。常见的名称变更：

OMT（旧）	Planet v4（当前）
transportation（class: motorway/primary/.../residential）	road（class: motorway/trunk/primary/secondary/tertiary/minor/service/...）；没有 residential 类——请使用 minor 或 service
transportation_name	road_label
（无——已合并）	railway、aviation、ferry、aerialway，各自为独立图层
place	country_label、city_label、island_label、continent_label（层级拆分）

当用户提示词引用 transportation、place 或其他 OMT 时代的图层名时，应明确指出名称变更，而不要默默生成无法使用的筛选条件。

架构	参考
Planet v4（最新）	map-resources-schemas-planet-v4.md
OpenMapTiles Planet	map-resources-schemas-omt-planet.md
Planet Lite	map-resources-schemas-planet-lite.md
Buildings	map-resources-schemas-buildings.md
Contours / Outdoor / Ocean	contours、outdoor、ocean
Landcover / Landform / Cadastre	landcover、landform、cadastre
样式规范（图层／数据源／表达式／根节点）	layers、sources、expressions、root

Buildings 瓦片集——始终优先使用（优先级规则）

专用的 buildings 瓦片集比嵌入 base-v4／streets-v4 的建筑数据丰富得多。任何 3D 拉伸、立面着色、建筑标签、入口或按要素交互，都应使用它。

关注项	标准（maptiler_planet_v4）	专用（buildings）
高度字段	render_height、render_min_height	height、height_min
颜色	—	facade_color、roof_color
形状	—	roof_shape
标签	—	building_label（名称、ISO 639 翻译）
入口	—	building_entrance
唯一 ID	False	True（z14+）——可与 setFeatureState 配合使用

// MapTiler SDK JS auto-injects the API key from config.apiKey — do NOT append ?key= manually.
map.addSource('buildings', {
  type: 'vector',
  url: 'https://api.maptiler.com/tiles/buildings/tiles.json',
});

// Facade color with fallback
'fill-extrusion-color': ['coalesce', ['get', 'facade_color'], 'hsl(44, 14%, 79%)']

SDK 之外（原生 MapLibre GL JS、移动端原生 style.json 请求、服务器端请求），请在 URL 后追加 ?key=YOUR_MAPTILER_API_KEY——不会自动注入。

关键字段映射：标准数据使用 render_height／render_min_height；专用数据使用 height／height_min。混用会导致渲染静默失败。

SDK 防护规则——ColorRamp 幻觉

JS SDK 的 ColorRamp 类不包含 .getExpression() 或 .getCSSGradientDirection()。要构建样式，请遍历 ColorRamp.getRawColorStops()，并手动构造标准的 MapLibre 插值表达式。

DDS 深入探讨

complex-dds-expressions-guide.md — 用于数据驱动样式的可组合模式。

---

8. Cloud REST API

所有 SDK API 模块都会自动使用 config.apiKey。如需在非 JS 环境中使用，请参阅 REST 文档。

模块	用途	主要方法 / 参考
geocoding	地点搜索、反向查询	forward()、reverse()、batch() — cloud-api-geocoding.md
geolocation	IP 访客位置	info() — cloud-api-geolocation.md
elevation	海拔查询	at()、batch()、fromLineString() — cloud-api-elevation.md
staticMaps	静态地图图像	centered()、bounded()、automatic() — cloud-api-static-maps.md
coordinates	CRS / EPSG 转换	search()、transform() — cloud-api-coordinates.md
data	MapTiler 数据集	get(uuid) — cloud-api-data.md
weather	风、温度、气压、雷达	cloud-api-weather.md
maps（矢量 / 栅格）	瓦片集、样式	cloud-api-maps.md
tiles	原始瓦片端点	cloud-api-tiles.md
fonts / images / ogc	其他	fonts、images、ogc
管理（瓦片集、上传、密钥、分析）	账户管理	cloud-admin-api-tilesets.md、api-keys、analytics
身份验证	密钥与令牌、来源站点规则	cloud-api-authentication.md

// IP geolocation
const loc = await maptilersdk.geolocation.info();

// Elevation — returns [lng, lat, elevationMeters]
const point = await maptilersdk.elevation.at([14.4178, 50.1167]);

---

9. 原生移动 SDK

平台	概览	API 参考
iOS（Swift）	mobile-sdks-ios.md	mobile-sdks-ios-api-classes.md
Android（Kotlin）	mobile-sdks-android.md	mobile-sdks-android-api-com-maptiler-maptilersdk-map.md
Flutter	mobile-sdks-flutter.md	搜索 mobile-sdks-flutter-*.md
React Native	mobile-sdks-react-native.md	搜索 mobile-sdks-react-native-*.md

iOS — 最简地图（SwiftUI）

import SwiftUI
import MapTilerSDK

struct ContentView: View {
    @State private var map = MTMapView(options: MTMapOptions(zoom: 2.0))

    var body: some View {
        MTMapViewContainer(map: map) {}
            .referenceStyle(.streets)
            .styleVariant(.defaultVariant)
            .task { await MTConfig.shared.setAPIKey("YOUR_MAPTILER_API_KEY") }
    }
}

MTConfig.shared.setAPIKey(_:) 是 async，且必须在初始化地图前调用。对于 Swift 6，请在 Task / .task 修饰符中调用。UIKit 替代方案：在 viewDidLoad 中声明 MTMapView(frame:options:referenceStyle:)，并调用 pinToSuperviewEdges()。

Android — 最简地图（Jetpack Compose）

// build.gradle.kts (app):  implementation("com.maptiler:maptiler-sdk-kotlin:<version>")
// AndroidManifest.xml:    <uses-permission android:name="android.permission.INTERNET" />
//                         android:hardwareAccelerated="true"

import com.maptiler.maptilersdk.config.MTConfig
import com.maptiler.maptilersdk.map.*

@Composable
fun MapScreen(context: Context) {
    MTConfig.apiKey = "YOUR_MAPTILER_API_KEY"        // set before first map
    val controller = remember { MTMapViewController(context) }
    MTMapView(
        referenceStyle = MTMapReferenceStyle.STREETS,
        options = MTMapOptions(),
        controller = controller,
        modifier = Modifier.fillMaxSize(),
    )
}

XML/View 变体：在布局中使用 MTMapViewClassic，并在 onCreate 中调用 mapView.initialize(referenceStyle, options, controller, styleVariant = null)。

可运行示例：搜索 examples-ios-*.md、examples-android-*.md。有关原始 style.json URL 的用法约定（UIKit、XML/View、自定义资源路径），请参阅 § 2B。

---

10. 本地部署 — 服务与引擎

适用于可自托管部署和离线切片生成：

主题	参考文档
MapTiler Server — 入门指南	on-prem-server-getting-started.md
托管数据	on-prem-server-hosting-data.md
虚拟切片集	on-prem-server-virtual-tilesets.md
服务端地图样式	on-prem-server-map-styling.md
本地部署地理编码	on-prem-server-geocoding.md
Engine CLI — 入门指南	on-prem-engine-getting-started-cli.md
Engine — 输入／输出选项	输入、输出

有关回退 XYZ 图层和 service-worker 缓存的切片路径约定，请参阅 § 2B。

---

11. 跨平台关键注意事项

问题	解决方法
地图不可见（Web）	容器需要显式设置高度（100vh 或 position: absolute; inset: 0）
标记 / 地图中心位于错误的大洲	坐标顺序是 [lng, lat]，而不是 [lat, lng]（例如，布拉格的坐标是 [14.4178, 50.1167]，而不是 [50.1167, 14.4178]）
调用 setStyle() 后图层消失	在 map.once('styledata', …) 中重新添加
数据遮挡标签	使用 beforeId: 'waterway-label'
点太多导致速度变慢	启用 cluster: true（辅助工具或数据源）
SPA 内存泄漏	卸载时始终调用 map.remove()；将引用设为 null
单独导入 maplibre-gl	使用 @maptiler/sdk——它包含并扩展了 MapLibre
React 中每次状态变化都会重新创建地图	useEffect 依赖项留空；通过 setX 方法修改，而不是重新初始化
处理程序中出现过时闭包	使用 useRef 镜像保存状态，并读取 .current
浏览器 ESM 脚本错误	搭配 <script type="module"> 使用 .mjs 构建版本，而不是 UMD
移动端渲染的 3D 建筑看起来很平	你加载了标准样式——添加专用的 buildings 数据源
移动端样式返回 404	将端点从 streets-v2 系列更新为 streets-v4 系列
地理编码密钥返回 403	在密钥设置中检查引用来源 / 白名单（cloud-api-authentication.md）
输出中泄漏 {{ }}	输出前通过 versions.md 解析
MapTiler Engine 无法启动	-o output_dir（或 -o file.mbtiles）目标必须尚不存在。删除该目标，或选择新路径。没有 -f / --force 标志
iOS 应用的每个瓦片请求都返回 403	MTConfig.shared.setAPIKey(_:) 是 async，但调用时没有使用 await——在第一个地图视图出现之前，将其放入 Task { … } 或 SwiftUI .task 修饰符中设置
mapbox-gl-draw 光标 / 命中测试异常	插件 CSS 针对 .mapboxgl-canvas；MapTiler/MapLibre 使用 .maplibregl-canvas。添加备用规则：.maplibregl-canvas.mouse-add { cursor: crosshair } 和 .maplibregl-canvas.mouse-drag { cursor: grabbing }
用户在聊天中粘贴了正在使用的 API 密钥	标记该密钥（在 Cloud Console 中轮换），并在你自己的输出中使用 YOUR_MAPTILER_API_KEY 占位符——切勿原样回显真实密钥
臆造 addControl(new XControl()) 模式	许多 MapTiler 控件是构造函数标志：minimap、navigationControl、geolocateControl、scaleControl、terrainControl、fullscreenControl、projectionControl。优先使用标志；仅在使用第三方插件或初始化后更改时才使用 addControl
臆造 SDK 类名（MinimapControl、GeocodingBar 等）	输出类名之前，请对照 references/sdk-js-controls.md 和 sdk-js-map.md。规范的迷你地图类名是 MaptilerMinimapControl（带 Maptiler 前缀），而构造函数选项通常更适用
GeoSplats 渲染失败 / 模型空白	GeoSplats SDK 需要 WebGPU 支持。务必检查浏览器兼容性（navigator.gpu），并提供清晰的 UI 备用错误覆盖层

---

12. 生态系统软件包

软件包	用途
@maptiler/geosplats	高性能 3D Gaussian Splatting（由 WebGPU 驱动）
@maptiler/geocoding-control	地址搜索栏 UI
@maptiler/weather	风、温度、气压、雷达图层（60 fps）
@maptiler/3d	glTF / GLB 3D 模型放置
@maptiler/elevation-profile	路线高程图表
@maptiler/marker-layout	不重叠的 DOM 标记覆盖层
@maptiler/ar	增强现实 3D 地形
@maptiler/client	无头 API 客户端（Node.js / 浏览器，无地图）

---

13. 资源

• MapTiler Cloud 控制台
• MapTiler SDK JS 文档 · 示例 · NPM · GitHub
• MapTiler iOS SDK 文档 · Android SDK 文档
• MapLibre 样式规范
• 框架文档：React · Vue · Svelte · Angular · Vite

---

14. 参考目录

精选的高价值参考文档索引位于 references/INDEX.md。对于未在其中列出的文件，请按照 § 1 中的前缀约定进行搜索。