deck.gl 与 Leaflet 叠加可视化实战：基于纯 JS 示例的完整指南

本指南围绕仓库中examples/get-started/pure-js/leaflet官方示例展开，讲解如何通过社区桥接库deck.gl-leaflet将 deck.gl 的 WebGL 图层叠加到 Leaflet 地图之上，实现"底图 + 大数据可视化图层"的经典组合。读完本文，你将掌握基于 Vite 的工程搭建、LeafletLayer的接入方式、GeoJsonLayer与ArcLayer的叠加配置，以及无构建工具的 CDN 快速方案。

Leaflet 与 deck.gl 的集成定位：叠加式（Overlaid）

deck.gl 本身可以脱离任何地图独立运行，但在展示地理空间数据时，底图能提供不可或缺的上下文。官方文档 docs/get-started/using-with-map.md 将 deck.gl 与底图渲染器的集成分为两类：

• Overlaid（叠加式）：Deck 的画布作为独立 DOM 元素渲染在底图之上，两者的相机保持同步，可一起平移/缩放。由于两个库各自独立管理渲染，这是更稳健的方案，通常足以满足 2D 底图场景。
• Interleaved（交织式）：Deck 直接渲染进底图的 WebGL2 上下文，可与底图的标注或 3D 要素产生遮挡关系，但依赖底图方案暴露特定开发者 API，可能受其缺陷限制。

在官方底图支持矩阵中，Leaflet 属于纯 JavaScript、Overlaid 模式的集成方案（该表还同时列出了 ArcGIS、Google Maps、harp.gl、Mapbox GL JS、MapLibre GL JS、OpenLayers、Apple Maps 等集成）。本文示例正是这一模式的完整落地。

示例工程结构

examples/get-started/pure-js/leaflet目录下仅包含 4 个文件，是一个极简但完整的 Vite 工程：

依赖声明（package.json）如下：

• @deck.gl/core：^9.0.0，提供MapView等视图类；
• @deck.gl/layers：^9.0.0，提供GeoJsonLayer、ArcLayer等核心图层；
• deck.gl-leaflet：^1.1.1，Leaflet 与 deck.gl 之间的桥接层；
• leaflet：^1.7.1，底图渲染库；
• vite（devDependencies）：^7.3.3，开发服务器与打包工具。

安装与运行

安装依赖

在示例目录下执行（README 中给出了两种等价方式）：

npm install # 或 yarn

开发与构建命令

README 中定义了三个脚本（package.json）：

• npm start：开发目标，启动 Vite 开发服务器并自动打开浏览器（vite --open），支持热更新（Hot Module Replacement）；
• npm run start-local：以仓库根目录下的 vite.config.local.mjs 为配置启动，便于在 monorepo 环境下使用本地源码模块而非已发布版本；
• npm run build：生产目标，执行vite build生成最终打包产物并写入磁盘。

页面骨架：index.html

index.html 的结构非常精简：

• 通过<link>引入 unpkg 托管的 Leaflet 样式表leaflet@1.7.1/dist/leaflet.css；
• 内联样式将#map容器设置为全屏（100vw × 100vh、绝对定位）；
• 页面主体只有一个<div id="map">；
• 以<script type="module" src='app.js'>方式加载 ES Module 入口。

从这里可以看出：deck.gl 的叠加模式并不需要修改 Leaflet 的 DOM 结构，只需保证一个地图容器存在即可。

核心代码解析：app.js

导入与数据源

import * as L from 'leaflet'; import {LeafletLayer} from 'deck.gl-leaflet'; import {MapView} from '@deck.gl/core'; import {GeoJsonLayer, ArcLayer} from '@deck.gl/layers';

示例使用 Natural Earth 的全球机场数据（经 geojson.xyz 分发），数据源为：

const AIR_PORTS = 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_airports.geojson';

这份 GeoJSON 同时被点图层与弧图层复用，展示 deck.gl 图层对同一数据源的多样解读。

初始化 Leaflet 地图与底图

const map = L.map(document.getElementById('map'), { center: [51.47, 0.45], zoom: 4 }); L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors' }).addTo(map);

这里先创建一个以伦敦附近为中心、缩放级别 4 的 Leaflet 地图，并叠加 OpenStreetMap 瓦片层作为底图。Leaflet 完全按照其原生 API 使用，deck.gl 不干预底图的创建过程——这正是 Overlaid 模式"各自独立管理渲染"的体现。

创建 LeafletLayer 桥接层

const deckLayer = new LeafletLayer({ views: [ new MapView({ repeat: true }) ], layers: [...] }); map.addLayer(deckLayer);

LeafletLayer是deck.gl-leaflet提供的核心桥接类，它继承自 Leaflet 的Layer接口，因此可以直接通过map.addLayer()加入地图。它内部负责：

1. 创建/管理 Deck 实例（默认挂载一个与 Leaflet 地图视口对齐的 canvas 覆盖层）；
2. 监听 Leaflet 的移动、缩放事件，把底图相机状态同步给 deck.gl；
3. 将配置的layers交给 Deck 渲染。

其中views配置了MapView，并开启repeat: true——允许地图在水平方向重复绘制，这在跨 180° 经线平移或低缩放级别浏览全球数据时非常有用（deck.gl 的MapView默认即启用重复，这里显式声明以保证跨经线区域图层不出现缝隙）。

机场点图层：GeoJsonLayer

new GeoJsonLayer({ id: 'airports', data: AIR_PORTS, // 样式 filled: true, pointRadiusMinPixels: 2, pointRadiusScale: 2000, getPointRadius: f => 11 - f.properties.scalerank, getFillColor: [200, 0, 80, 180] })

• data直接传入 GeoJSON 数据，GeoJsonLayer会自动解析Point/MultiPoint要素；
• pointRadiusScale: 2000与pointRadiusMinPixels: 2共同控制点的屏幕大小：前者将地理半径按比例放大，后者保证即使地图缩小到很远，点半径也不会小于 2 像素，避免点消失；
• getPointRadius是访问器（accessor），基于要素属性scalerank（Natural Earth 的等级字段）计算半径：等级越小半径越大，直观呈现机场重要性差异；
• getFillColor使用带透明度的洋红色[200, 0, 80, 180]。

航线弧图层：ArcLayer

new ArcLayer({ id: 'arcs', data: AIR_PORTS, dataTransform: d => d.features.filter(f => f.properties.scalerank < 4), // 样式 getSourcePosition: f => [-0.4531566, 51.4709959], // 伦敦 getTargetPosition: f => f.geometry.coordinates, getSourceColor: [0, 128, 200], getTargetColor: [200, 0, 80], getWidth: 1 })

• dataTransform在数据进入图层前做预处理：只保留scalerank < 4的机场，即仅对"大型/重要机场"绘制弧线，避免画面过载——这是 deck.gl 数据访问器体系中非常实用的过滤手段；
• getSourcePosition固定为伦敦的经纬度[-0.4531566, 51.4709959]，表示所有弧线从伦敦出发；
• getTargetPosition取每个要素的geometry.coordinates作为目标点，形成"伦敦 → 全球机场"的辐射航线图；
• 起点为蓝色、终点为洋红，弧线宽度 1。

与 Leaflet 原生要素混用

const featureGroup = L.featureGroup(); featureGroup.addLayer(L.marker([51.4709959, -0.4531566])); map.addLayer(featureGroup);

示例最后还添加了一个原生 Leaflet 标记（伦敦位置）。这验证了 Overlaid 模式的关键优势：deck.gl 图层与 Leaflet 原生要素（Marker、Polyline、Popup 等）可以共存于同一地图上，前者负责高性能大数据渲染，后者继续承担交互标注等常规职责。

无构建工具方案：scripting 版本

如果不想引入 Node/Vite 构建链，仓库还提供了 CDN 直引版本 examples/get-started/scripting/leaflet/index.html，通过<script>标签依次引入：

<script src="https://unpkg.com/leaflet@1.7.1/dist/leaflet.js"></script> <script src="https://unpkg.com/deck.gl@^9.0.0-beta.2/dist.min.js"></script> <script src="https://unpkg.com/deck.gl-leaflet@1.1.1/dist/deck.gl-leaflet.min.js"></script>

脚本中使用全局命名空间（DeckGlLeaflet.LeafletLayer、deck.MapView、deck.GeoJsonLayer等）实现与模块版完全一致的叠加逻辑。这种方案适合快速原型验证或无法使用打包工具的场景，但需要浏览器支持 ES 模块与现代 WebGL2 能力。

注意事项

• WebGL2 要求：如 docs/get-started/using-with-map.md 所述，Deck 无法渲染到 WebGL1 上下文，请确保运行环境（浏览器/设备）支持 WebGL2。
• 许可与归属：本示例基于社区维护的deck.gl-leaflet桥接库（作者 Jan Žák），README 的 Attribution 一节已明确声明该归属，使用时应遵守其开源许可。
• 数据合规：示例使用了 Natural Earth（经 geojson.xyz）与 OpenStreetMap 数据。官方文档同时提醒：使用底图时务必遵循所依赖 JS 库与数据提供方各自的服务条款与署名要求。

延伸阅读

• 底图集成总览与 Overlaid/Interleaved 模式对比：docs/get-started/using-with-map.md
• 其他纯 JS 底图集成示例（ArcGIS、harp.gl、OpenLayers、Apple Maps 等）：examples/get-started/pure-js
• 图层 API 参考：GeoJsonLayer、ArcLayer、MapView