Leaflet 加载 GeoJSON 矢量数据

WebGIS
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

Leaflet 用 GeoJSON 类把符合 RFC 7946 的矢量数据挂到地图上,支持 Point、LineString、Polygon 以及各类 Multi 与 GeometryCollection;实践中优先用 Feature / FeatureCollection,因为可带 properties 做样式和交互。1.x 常用 L.geoJSON(data).addTo(map),2.0 则是 new GeoJSON(data).addTo(map)(也可先建空层再 addData)。坐标必须是 [经度, 纬度],远程数据用 fetch 取回 JSON 再加入即可。

Leaflet 地图上叠加 GeoJSON 点线面要素的示意

怎么把 GeoJSON 加到地图上

前提是地图已创建并设好中心与底图。下面以稳定版 1.9.x 写法为主(目前 npm 默认仍是 1.9.4),并注明 2.0 beta 的对应写法,方便你对照项目版本。

  1. 准备合法 GeoJSON:推荐 FeatureCollection;多边形外环需闭合,并尽量符合 RFC 7946 右手规则。
  2. 把数据变成 JS 对象:内联常量、或 fetch(‘/path/data.geojson’).then(r => r.json()) 得到对象。
  3. 创建图层并加入地图。1.x:const layer = L.geoJSON(data).addTo(map);。2.0:先 import { GeoJSON } from ‘leaflet’,再 const layer = new GeoJSON(data).addTo(map);。
  4. 按需缩放到数据范围:map.fitBounds(layer.getBounds())。
  5. 需要分批追加时,先 L.geoJSON() / new GeoJSON() 建空层,再多次调用 addData(fragment)。

加载失败(空白、报 Invalid GeoJSON、CORS)时,先看网络是否 200、响应是否真是 JSON,再对照本站排查文:Leaflet加载GeoJSON失败:读取GeoJSON排查。

样式、点符号和弹窗怎么配

GeoJSON 层继承 FeatureGroup,常用 options 如下;点默认是 Marker,面/线走 Path 样式。

选项 作用 典型用法
style 统一样式,或按要素返回 Path 选项 对象:{color:’#3388ff’, weight:2};函数:根据 feature.properties 换色
pointToLayer 自定义点的渲染图层 (feature, latlng) => L.circleMarker(latlng, {radius:6})(2.0 用 CircleMarker)
onEachFeature 每个要素创建后的回调 绑定弹窗、事件;不信任数据时勿直接拼 HTML
filter 返回 true/false 控制是否加入 按属性筛掉不需要的要素
  • 分级设色:把 style 写成函数,读属性分级返回 fillColor 等,官方 choropleth 示例就是同一思路。
  • 悬停高亮:在 onEachFeature 里监听 mouseover 改样式,mouseout 调用图层的 resetStyle。
  • 弹窗安全:来源不可信时,用纯文本或先消毒再 bindPopup,避免 XSS。

点要素若只写 style 而不写 pointToLayer,样式往往看不出效果——点默认不是 Path,需要返回 CircleMarker 等才吃 Path 选项。

远程文件、坐标系和性能要注意什么

GeoJSON 标准坐标系是 WGS84(EPSG:4326),字段顺序是 [lng, lat]。Leaflet 的 LatLng 习惯是 [lat, lng],两者容易搞反:点会漂到海里或飞到错误半球。非 WGS84 数据要先在库外重投影,不要指望 Leaflet 默认识别旧版 GeoJSON 的 crs 成员(RFC 7946 已弃用)。

  • 远程加载:用 fetch / XHR;服务器需允许跨域。不要把文件路径字符串直接当成 GeoJSON 对象传给构造函数。
  • 本地文件:浏览器环境需用户选择文件再 FileReader 读文本,或借助插件;服务端同源托管最省事。
  • 大数据:几何先简化,或改用矢量瓦片 / Canvas 相关插件;整份上万复杂多边形直接塞进 GeoJSON 层容易卡顿。
  • 验收:要素位置与桌面 GIS 一致、缩放 getBounds() 合理、弹窗属性正确、控制台无 Invalid GeoJSON。

读文件报错、结构校验、坐标翻转等问题的逐步排查,见 读取 GeoJSON 失败的排查步骤。

Leaflet 2.0.0-beta.2 在 GitHub Releases 上的发布说明页
Leaflet 2.0.0-beta.2 在 GitHub Releases 上的发布说明页(截图来源:github.com)

1.x 与 2.0 写法差在哪

截至 2026 年 11 月,生产环境多数仍是 Leaflet 1.9.4(2023-05-18);2.0.0-beta.2 约在 2026-11-06 发布,官方 GeoJSON 教程与参考默认按 2.0 写。2.0 改为纯 ES 模块类、可 tree-shake,构造方式从全局 L.geoJSON 变为 import { GeoJSON, … } from ‘leaflet’ 后 new GeoJSON(…)。CDN 可用 importmap 指向对应版本;升级前先看迁移说明,并确认插件是否标注支持 Leaflet 2。版本包可在 Leaflet 2.0.0-beta.2 发布页 核对。

常见问题

为什么 GeoJSON 加进去什么都看不到?

先查坐标是否写成了 [lat, lng]、图层是否已 addTo(map)、数据是否为 Feature/FeatureCollection,以及当前视图是否在数据范围内;用 fitBounds 和浏览器 Network/Console 很快能定位。

style 改了颜色,点怎么还是默认图标?

style 主要作用于线面 Path;点请在 pointToLayer 里返回 CircleMarker(或自定义图层)并带上颜色半径等选项。

Polygon 显示成“翻面”或有空洞异常怎么办?

检查环是否闭合、绕向是否符合规范、内环是否正确;用校验工具修几何后再加载。部分复杂 MultiPolygon 在旧版本偶发渲染问题,可升级 Leaflet 或拆分要素验证。

大数据一卡一顿怎么处理?

先简化顶点、按需 filter、避免一次绑定过重 DOM 弹窗;更大范围数据改走矢量瓦片或分块 addData,而不是整库塞进一个 GeoJSON 层。

总结:把合法 GeoJSON(优先 FeatureCollection)用 L.geoJSON / new GeoJSON 加入已有地图,配好 style、pointToLayer、onEachFeature,并始终守住 [lng, lat] 与 WGS84。建议你先用一小份已知正确的样例跑通 addTo + fitBounds,再接业务数据和样式;加载异常时按本站《Leaflet加载GeoJSON失败》一文逐项核对路径、CORS 与数据结构。