项目地址: 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
leafletdist-taglatest与 GitHub Release 一致;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
<!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
npm install leaflet
import L from 'leaflet';
import 'leaflet/dist/leaflet.css';
验证
打开页面应看到可拖拽、可缩放的 OSM 底图;控制台执行 L.version 返回 "1.9.4"。
console.log(L.version); // "1.9.4"
核心 API
L.map
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
L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
maxZoom: 19,
subdomains: 'abc',
attribution: '© OpenStreetMap contributors'
}).addTo(map);
URL 模板占位符:{s} 子域、{z} 层级、{x}/{y} 瓦片坐标、{r} 高清后缀(@2x)。
L.marker
const marker = L.marker([39.9087, 116.3975], {
draggable: true,
title: '天安门'
}).addTo(map);
marker.bindPopup('天安门广场').openPopup();
L.geoJSON
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 与图层控制
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。
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]),输出可缩放、可点选、可切层的单页地图。
- 初始化地图:
L.map('map', { center, zoom }),容器须有确定高度 - 添加底图:
L.tileLayer(urlTemplate, { attribution }).addTo(map) - 叠加数据:
L.geoJSON(data, { style, pointToLayer, onEachFeature }) - 绑定交互:
layer.bindPopup()/map.on('click', fn) - 图层管理:
L.control.layers(baseLayers, overlays).addTo(map) - 自适应视图:
map.fitBounds(layer.getBounds()) - 销毁清理:组件卸载时调用
map.remove()
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: '© 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 |
基于点数据的热力图图层 |
// 绘制控件
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));
// 点聚合
import 'leaflet.markercluster';
import 'leaflet.markercluster/dist/MarkerCluster.css';
const cluster = L.markerClusterGroup();
cluster.addLayer(L.marker([39.9, 116.4]));
map.addLayer(cluster);
// 热力图
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
<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
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 }} />;
}
最佳实践
- 容器高度:
#map必须有显式高度(如height: 400px),否则渲染为 0 高度不可见 - 及时销毁:单页应用卸载组件时调用
map.remove(),清除事件与 DOM - 事件解绑:自定义监听器用具名函数并通过
map.off(type, handler)移除 - 大数据量:数千点以上使用
leaflet.markercluster聚合,避免逐点渲染卡顿 - 避免重复初始化:同一容器仅调用一次
L.map(),重复调用需先remove() - 正确坐标顺序:Leaflet 使用
[纬度, 经度],与 GeoJSON 的[经度, 纬度]相反 - 版权声明:使用 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 的integritySRI 哈希只对应 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
- cesiumjs — 三维地球与 3D Tiles 可视化:../cesiumjs/SKILL.md
- geoserver — 发布 WMS/WFS/瓦片服务作为 Leaflet 数据源:../geoserver/SKILL.md