# Leaflet

> Use when adding lightweight 2D tile maps to web pages with leaflet 1.9.4 — L.map/L.tileLayer, markers, popups, GeoJSON overlays, layer control, [lat, lng] ordering, or debugging blank maps, broken default marker icons after bundling, and sizing fixed by invalidateSize().

- Skill: `znlgis/leaflet` (Agent Skill)
- Install (CLI): `npx get-skill add znlgis/leaflet`
- Raw SKILL.md: https://api.skillmd.com/api/skills/znlgis/leaflet/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: znlgis (https://skillmd.com/u/znlgis)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/znlgis/leaflet

---


> **项目地址：** <https://github.com/Leaflet/Leaflet>
>
> **官方文档：** <https://leafletjs.com/>
>
> **API 参考：** <https://leafletjs.com/reference.html>
>
> **示例：** <https://leafletjs.com/examples.html>
>
> **最新版本：** 1.9.4（截至 2026-11，[npm `leaflet`](https://www.npmjs.com/package/leaflet) dist-tag `latest` 与 [GitHub Release](https://github.com/Leaflet/Leaflet/releases) 一致；1.9.4 发布于 2023-05，仍是**当前稳定版**。2.0 尚在 beta 阶段（`v2.0.0-beta.3`，2026-11-10），未发布稳定版，生产环境沿用 1.x）
>
> **许可证：** BSD-2-Clause

## 概述

Leaflet 是面向移动端与桌面端的开源 2D 地图库，核心构建体积约 42 KB，提供命令式的类 jQuery API。特性：

- **瓦片图层**：支持 OSM、XYZ、WMS、WMTS、ArcGIS 等栅格底图
- **矢量叠加**：Marker、Popup、Tooltip、Circle、Polygon、Polyline、GeoJSON
- **图层管理**：LayerGroup、FeatureGroup、`L.control.layers` 切换底图与叠加层
- **事件系统**：Map / Layer / Marker 均继承 `Evented`，统一 `on` / `off` / `once`
- **插件生态**：绘制、聚合、热力图、矢量瓦片等均有成熟第三方插件
- **框架无关**：可在原生 JS、Vue、React、Svelte 中直接使用

---

## 环境准备

### 方式一：CDN

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
        integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin="" />
  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
          integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
  <style>
    /* 容器必须显式设置高度，否则地图不可见 */
    #map { height: 400px; }
  </style>
</head>
<body>
  <div id="map"></div>
</body>
</html>
```

### 方式二：npm

```bash
npm install leaflet
```

```javascript
import L from 'leaflet';
import 'leaflet/dist/leaflet.css';
```

### 验证

打开页面应看到可拖拽、可缩放的 OSM 底图；控制台执行 `L.version` 返回 `"1.9.4"`。

```javascript
console.log(L.version); // "1.9.4"
```

---

## 核心 API

### L.map

```javascript
const map = L.map('map', {
  center: [39.9087, 116.3975], // [纬度, 经度]
  zoom: 12,
  zoomControl: true,
  attributionControl: true
});
```

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `center` | LatLng | 无 | 初始中心点 `[lat, lng]` |
| `zoom` | Number | 无 | 初始缩放级别 |
| `zoomControl` | Boolean | `true` | 是否添加缩放控件 |
| `attributionControl` | Boolean | `true` | 是否添加版权控件 |
| `minZoom` / `maxZoom` | Number | 无 | 缩放范围限制 |

### L.tileLayer

```javascript
L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
  maxZoom: 19,
  subdomains: 'abc',
  attribution: '&copy; OpenStreetMap contributors'
}).addTo(map);
```

URL 模板占位符：`{s}` 子域、`{z}` 层级、`{x}`/`{y}` 瓦片坐标、`{r}` 高清后缀（`@2x`）。

### L.marker

```javascript
const marker = L.marker([39.9087, 116.3975], {
  draggable: true,
  title: '天安门'
}).addTo(map);

marker.bindPopup('天安门广场').openPopup();
```

### L.geoJSON

```javascript
L.geoJSON(geojsonData, {
  style: (feature) => ({ color: '#ff7800', weight: 2 }),
  pointToLayer: (feature, latlng) => L.circleMarker(latlng, { radius: 6 }),
  onEachFeature: (feature, layer) => {
    layer.bindPopup(feature.properties.name);
  },
  filter: (feature) => feature.properties.show !== false
}).addTo(map);
```

| 选项 | 签名 | 用途 |
|------|------|------|
| `style` | `(feature) => Path options` | 面/线样式，可传对象或函数 |
| `pointToLayer` | `(feature, latlng) => Layer` | 自定义点渲染（如圆点替代默认图标） |
| `onEachFeature` | `(feature, layer) => void` | 为每个要素绑定弹窗、事件 |
| `filter` | `(feature) => Boolean` | 返回 `false` 的要素不渲染 |
| `coordsToLatLng` | `(coords) => LatLng` | 自定义坐标转换 |

### L.layerGroup 与图层控制

```javascript
const baseLayers = {
  'OSM': L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png'),
  '高德影像': L.tileLayer('https://webst02.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}')
};

const points = L.layerGroup([marker]);
const overlays = { '标注点': points };

L.control.layers(baseLayers, overlays).addTo(map);
baseLayers['OSM'].addTo(map); // 默认底图需手动添加
```

### 事件系统

`Map`、`Layer`、`Marker` 均继承 `Evented`，使用 `on` / `off` / `once` / `fire`。

```javascript
map.on('click', (e) => console.log(e.latlng));
map.on('zoomend moveend', () => console.log(map.getZoom()));

marker.on('click', () => console.log('marker clicked'));
marker.on('dragend', () => console.log(marker.getLatLng()));

const handler = (e) => console.log(e);
map.on('mousemove', handler);
map.off('mousemove', handler); // 显式移除，避免内存泄漏
```

常用 Map 事件：`click`、`dblclick`、`mousemove`、`zoomend`、`moveend`、`layeradd`、`layerremove`、`resize`、`popupopen`。

---

## 典型工作流

以「底图 + GeoJSON 点位 + 弹窗 + 图层切换」为例：输入 `data/poi.geojson`（`[lng, lat]`），输出可缩放、可点选、可切层的单页地图。

1. **初始化地图**：`L.map('map', { center, zoom })`，容器须有确定高度
2. **添加底图**：`L.tileLayer(urlTemplate, { attribution }).addTo(map)`
3. **叠加数据**：`L.geoJSON(data, { style, pointToLayer, onEachFeature })`
4. **绑定交互**：`layer.bindPopup()` / `map.on('click', fn)`
5. **图层管理**：`L.control.layers(baseLayers, overlays).addTo(map)`
6. **自适应视图**：`map.fitBounds(layer.getBounds())`
7. **销毁清理**：组件卸载时调用 `map.remove()`

```javascript
const map = L.map('map', { center: [39.9042, 116.4074], zoom: 11 });

const osm = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
  maxZoom: 19,
  attribution: '&copy; OpenStreetMap contributors'
}).addTo(map);

// GeoJSON 坐标是 [lng, lat]，Leaflet 需要 [lat, lng]
fetch('/data/poi.geojson')
  .then((r) => r.json())
  .then((geojson) => {
    const poiLayer = L.geoJSON(geojson, {
      pointToLayer: (feature, latlng) => L.circleMarker(latlng, { radius: 6, color: '#e74c3c' }),
      onEachFeature: (feature, layer) => {
        layer.bindPopup(feature.properties.name);
      }
    }).addTo(map);

    map.fitBounds(poiLayer.getBounds(), { padding: [20, 20] });
    L.control.layers({ OSM: osm }, { POI: poiLayer }).addTo(map);
  });
```

**验收**：页面先出现 OSM 底图，数据加载后视野自动收缩到点位范围，点击圆点弹出名称；右上角图层控件可切换 POI 显隐。

---

## 插件生态

插件通过 `L.xxx` 扩展，使用时先引入其 CSS/JS，再调用扩展 API。

| 插件 | npm 包名 | 用途 |
|------|----------|------|
| Leaflet.draw | `leaflet-draw` | 交互式绘制/编辑几何（点、线、面、矩形、圆） |
| Leaflet.markercluster | `leaflet.markercluster` | 大量点标记的聚合与展开动画 |
| Leaflet.heat | `leaflet.heat` | 基于点数据的热力图图层 |

```javascript
// 绘制控件
import 'leaflet-draw';
import 'leaflet-draw/dist/leaflet.draw.css';

const drawnItems = new L.FeatureGroup().addTo(map);
map.addControl(new L.Control.Draw({ edit: { featureGroup: drawnItems } }));
map.on(L.Draw.Event.CREATED, (e) => drawnItems.addLayer(e.layer));
```

```javascript
// 点聚合
import 'leaflet.markercluster';
import 'leaflet.markercluster/dist/MarkerCluster.css';

const cluster = L.markerClusterGroup();
cluster.addLayer(L.marker([39.9, 116.4]));
map.addLayer(cluster);
```

```javascript
// 热力图
import 'leaflet.heat';

const heat = L.heatLayer([[39.9, 116.4, 0.5], [39.91, 116.41, 0.8]], { radius: 25 });
heat.addTo(map);
```

---

## 与 Vue / React 集成

核心原则：**用 ref / state 持有 map 实例，在挂载时创建、卸载时 `map.remove()`**，避免重复初始化和内存泄漏。

### Vue 3

```vue
<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import L from 'leaflet';
import 'leaflet/dist/leaflet.css';

const mapEl = ref(null);
let map = null;

onMounted(() => {
  map = L.map(mapEl.value).setView([39.9087, 116.3975], 12);
  L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);
});

onBeforeUnmount(() => {
  map?.remove();
  map = null;
});
</script>

<template>
  <div ref="mapEl" style="height: 400px"></div>
</template>
```

### React

```jsx
import { useEffect, useRef } from 'react';
import L from 'leaflet';
import 'leaflet/dist/leaflet.css';

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

  useEffect(() => {
    const map = L.map(containerRef.current).setView([39.9087, 116.3975], 12);
    L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);
    mapRef.current = map;
    return () => {
      map.remove();
      mapRef.current = null;
    };
  }, []);

  return <div ref={containerRef} style={{ height: 400 }} />;
}
```

---

## 最佳实践

1. **容器高度**：`#map` 必须有显式高度（如 `height: 400px`），否则渲染为 0 高度不可见
2. **及时销毁**：单页应用卸载组件时调用 `map.remove()`，清除事件与 DOM
3. **事件解绑**：自定义监听器用具名函数并通过 `map.off(type, handler)` 移除
4. **大数据量**：数千点以上使用 `leaflet.markercluster` 聚合，避免逐点渲染卡顿
5. **避免重复初始化**：同一容器仅调用一次 `L.map()`，重复调用需先 `remove()`
6. **正确坐标顺序**：Leaflet 使用 `[纬度, 经度]`，与 GeoJSON 的 `[经度, 纬度]` 相反
7. **版权声明**：使用 OSM 等底图时在 `attribution` 中保留版权信息

---

## 常见问题

| 报错 / 现象 | 原因 | 处置 |
|------|------|------|
| 报错 `Uncaught Error: Map container is already initialized.` | 同一个 DOM 容器被 `L.map()` 初始化两次（React StrictMode 双调用、热更新、路由复用组件最常见） | 复用前先 `map.remove()` 并把引用置空；React 在 `useEffect` 的 cleanup 里 `remove()`，初始化前判断容器是否已带 `_leaflet_id` |
| 报错 `Uncaught Error: Map container not found.` | `L.map(id)` 执行时容器 DOM 尚未挂载，或 id 与模板不一致 | 等 DOM 就绪再初始化（React `useEffect`、Vue `onMounted`），并核对传入的 id/元素 |
| 报错 `Uncaught Error: Map container is being reused by another instance` | 容器仍被一个未销毁的 `Map` 实例占用 | 先 `remove()` 旧实例再初始化；同一容器不要并存两个地图 |
| 报错 `Uncaught ReferenceError: L is not defined` | CDN 脚本未加载、加载失败，或自定义代码先于 `leaflet.js` 执行 | 先引 `leaflet.js` 再执行业务代码；npm 下确认 `import L from 'leaflet'` 且打包产物真的包含它 |
| 地图区域空白 / 不显示 | 容器没有显式高度（Leaflet 不自带尺寸），或初始化后容器尺寸才变化 | 给 `#map` 设 `height`（如 `400px`）；尺寸变化后调用 `map.invalidateSize()` |
| 默认标记图标 404 / 显示为破图 | npm + 打包器下 `leaflet.css` 里相对的默认图标路径失效 | 显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`，或改用 CDN 引入 CSS 与图片 |
| 地图在弹窗 / 隐藏容器中显示错乱 | 容器尺寸在初始化时已知为零，或标签页切回后尺寸变化 | 容器可见后再初始化，并在可见性变化后调用 `map.invalidateSize()` |
| 点跑到别的位置 / 坐标颠倒 | 参数顺序是 `[lat, lng]`，而 GeoJSON 是 `[lng, lat]` | 统一在入口处用 `L.latLng(lat, lng)` 或 `coordsToLatLng` 转换，不要混用两种顺序 |
| 组件切换后内存持续增长 | 卸载时未调用 `map.remove()`，或自定义事件未 `off` 解绑 | cleanup 中 `map.remove()`；自定义监听器用具名函数并 `map.off(type, handler)` |
| 瓦片加载失败 / 跨域报错 | 瓦片 URL 模板错误，或瓦片服务未返回 CORS 头 | 核对 `{z}/{x}/{y}` 模板与该服务实际路径；WMS 需服务端放行跨域，前端 `crossOrigin` 选项按需设置 |
| 地图与 Vue/React 响应式冲突 | 把 `L.map` 实例放进 `reactive`/`useState`，代理了 Leaflet 内部对象 | 用普通变量或 `useRef` 持有实例，不要放进响应式容器 |

---

## AI 使用建议

- **执行环境**：`npm install`、`npm run build` 在终端中执行；纯静态页面可用 `python -m http.server 5173` 起服务（`python` 不存在时用 `py -3`）。
- **先探测版本**：`npm ls leaflet`（未装则 `npm view leaflet version`）；本技能按 1.9.4 编写，CDN 的 `integrity` SRI 哈希只对应 1.9.4，换版本必须同步换哈希。Leaflet 2.0 目前只有 beta（`2.0.0-beta.3`），API 与插件兼容性仍在变动，回答里默认给 1.9.4 方案。
- **验证产物**：构建后 `curl.exe -I http://localhost:5173/assets/<入口>.js` 确认 200；联网时还可 `curl.exe -I https://unpkg.com/leaflet@1.9.4/dist/leaflet.js` 核对 CDN 版本；AI 助手通常看不到浏览器画面，把 URL 和“应看到瓦片与标记”交给用户，环境支持读图时用截图核对。
- **图标与坐标**：npm + 打包器下默认 marker 图标会 404，需显式设置 `L.Icon.Default` 的 `iconUrl`/`iconRetinaUrl`/`shadowUrl`；坐标一律 `[lat, lng]`，GeoJSON 是 `[lng, lat]`。
- **生命周期**：SPA 卸载必须 `map.remove()` 并解绑自定义事件；容器隐藏或尺寸变化后 `map.invalidateSize()`。
- **常见症状**：地图区域空白多为容器没设高度；`L is not defined` 是脚本顺序或 CDN 失败；漏引 `leaflet.css` 会导致控件错位。
- **安全与权限**：装包、起服务、改端口前先征得用户同意；天地图等瓦片服务的 `tk` 不要硬编码进提交的前端代码。

## 相关技能

- **openlayers** — 功能更全的 2D WebGIS 库（投影、MVT、高级交互）：[../openlayers/SKILL.md](../openlayers/SKILL.md)
- **cesiumjs** — 三维地球与 3D Tiles 可视化：[../cesiumjs/SKILL.md](../cesiumjs/SKILL.md)
- **geoserver** — 发布 WMS/WFS/瓦片服务作为 Leaflet 数据源：[../geoserver/SKILL.md](../geoserver/SKILL.md)

## 参考资源

- 官方文档：<https://leafletjs.com/>
- API 参考：<https://leafletjs.com/reference.html>
- 官方示例：<https://leafletjs.com/examples.html>
- 插件列表：<https://leafletjs.com/plugins.html>
- 源码仓库：<https://github.com/Leaflet/Leaflet>

