deck.gl × Mapbox 纯 JavaScript 集成实战从 Vite 示例到 MapboxOverlay 源码级解析【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl本篇技术指南以 deck.gl 仓库中的 pure-js/mapbox 示例 为核心骨架完整讲解如何用原生 JavaScript 与 Vite 将 deck.gl 图层叠加到 Mapbox GL 地图上从获取 Access Token、安装依赖、启动开发服务器到逐行拆解app.js中 GeoJsonLayer 与 ArcLayer 的配置并深入deck.gl/mapbox模块源码揭示MapboxOverlay实现相机同步、图层插入与事件转发的底层机制。读完后你将能独立搭建一个deck.gl 数据图层 Mapbox 底图的纯 JS 工程并理解 interleaved / overlaid 两种渲染模式的区别与选型。示例定位纯 JS Vite 的最小可运行工程示例位于仓库的 examples/get-started/pure-js/mapbox 目录它不依赖 React直接使用原生 JavaScript 通过mapbox-gl创建地图再借助deck.gl/mapbox的MapboxOverlay把 deck.gl 图层叠加上去。整个工程只有 5 个文件examples/get-started/pure-js/mapbox/ ├── app.js # 应用主逻辑地图初始化 deck.gl 图层 ├── index.html # 页面骨架与地图容器 ├── package.json # 依赖与 npm 脚本 ├── vite.config.js # Vite 配置注入环境变量 └── README.md # 运行说明根据 package.json工程依赖如下deck.gl/core^9.0.0deck.gl 运行时核心deck.gl/layers^9.0.0提供 GeoJsonLayer、ArcLayer 等内置图层deck.gl/mapbox^9.0.0提供MapboxOverlay负责与 mapbox-gl 深度集成mapbox-gl^3.0.0Mapbox 底图库vite^7.3.3devDependency开发服务器与打包器。示例 README 明确说明使用 Vite 负责打包与服务这是纯 JS 场景下最轻量的工程化方案零配置、按需编译、开发热更新生产构建输出可直接部署的静态资源。运行前置获取并注入 Mapbox Access TokenMapbox 的地图瓦片服务要求请求方携带 Access Token 以标识身份。官方集成指南 使用 Mapboxdocs/developer-guide/base-maps/using-with-mapbox.md 指出需要先在 Mapbox 官网注册并申请 token。README 给出了两种注入 token 的方式方式一设置环境变量推荐export MapboxAccessTokenmapbox_access_token在 vite.config.js 中Vite 通过define把环境变量在构建期替换进代码export default { define: { process.env.MapboxAccessToken: JSON.stringify(process.env.MapboxAccessToken) } };而 app.js 里读取的就是这个变量// Set your Mapbox token here or via environment variable const MAPBOX_TOKEN process.env.MapboxAccessToken; // eslint-disable-linedefine属于 Vite 的构建期常量替换这意味着开发服务器启动前环境变量就必须已经导出如果启动后再修改环境变量需要重启npm start才会生效。方式二直接在app.js中硬编码例如把第 15 行改为const MAPBOX_TOKEN mapbox_access_token;作为对比使用 react-map-gl 时还可以通过 URL 参数?access_tokenTOKEN或Map mapboxAccessToken{TOKEN} /prop 传入详见 使用 Mapbox 的 Mapbox Token 一节。注意Mapbox GL JS 自 2.0 起采用专有许可证即使不加载 Mapbox 服务器的瓦片也需要账户与 token如果希望完全脱离 Mapbox 服务可考虑 MapLibre GL JS见 使用 MapLibre或 mapbox-gl v1.13但后者不支持 interleaved 渲染。安装依赖与启动命令在示例目录下安装依赖npm 与 yarn 均可npm install # or yarn随后即可使用 package.json 中定义的脚本命令作用npm start开发模式启动 Vite 开发服务器并自动打开浏览器支持热更新对应vite --opennpm run start-local使用仓库根目录的 vite.config.local.mjs 启动用于在 monorepo 中直接引用本地源码模块调试npm run build生产构建生成最终 bundle 并写入磁盘对应vite buildnpm run start-local是 deck.gl monorepo 特有的脚本它让示例直接链接仓库内的本地模块源码而非 npm 上的发布包方便开发者调试 deck.gl 本身的改动普通使用者运行npm start即可。逐段拆解 app.js地图 图层 交互1. 导入与数据源app.js 开头的导入是本示例的核心依赖import {MapboxOverlay as DeckOverlay} from deck.gl/mapbox; import {GeoJsonLayer, ArcLayer} from deck.gl/layers; import mapboxgl from mapbox-gl; import mapbox-gl/dist/mapbox-gl.css;把MapboxOverlay别名成DeckOverlay仅为语义清晰它本质上是一个实现了 MapboxIControl接口的控件。数据源使用 Natural Earth 提供的全球机场 GeoJSON通过 geojson.xyz 的 CDN 分发覆盖全球约数千个机场点const AIR_PORTS https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_airports.geojson;2. 初始化 Mapbox 地图const map new mapboxgl.Map({ container: map, style: mapbox://styles/mapbox/light-v9, accessToken: MAPBOX_TOKEN, center: [0.45, 51.47], zoom: 4, bearing: 0, pitch: 30 });container: map对应 index.html 中的div idmap/div该容器通过 CSS 铺满整个视口地图中心设为伦敦经度 0.45、纬度 51.47初始缩放级别 4俯仰角 30°——倾斜视角正是后文 ArcLayer 弧形航线的最佳展示角度。3. 创建 MapboxOverlay 并挂载const deckOverlay new DeckOverlay({ // interleaved: true, layers: [ ... ] }); map.addControl(deckOverlay); map.addControl(new mapboxgl.NavigationControl());map.addControl(deckOverlay)把 overlay 作为 Mapbox 控件注册进地图MapboxOverlay的默认控件位置是top-left源码见 mapbox-overlay.ts 的getDefaultPosition()。代码中interleaved: true被注释掉因此默认走 overlaid 模式下一节会详述这两种模式的差异。注意示例没有把创建 overlay 放在map.once(load)回调里overlaid 模式下MapboxOverlay会在自己创建的独立 canvas 上渲染与底图加载状态解耦而 interleaved 模式需要共享底图的 WebGL2 上下文与样式图层栈官方文档示例using-with-mapbox.md通常放在map.once(load)中执行。4. GeoJsonLayer机场点位可视化new GeoJsonLayer({ id: airports, data: AIR_PORTS, // Styles filled: true, pointRadiusMinPixels: 2, pointRadiusScale: 2000, getPointRadius: f 11 - f.properties.scalerank, getFillColor: [200, 0, 80, 180], // Interactive props pickable: true, autoHighlight: true, onClick: info info.object alert(${info.object.properties.name} (${info.object.properties.absprev})) // beforeId: waterway-label // In interleaved mode render the layer under map labels })参数解读pointRadiusMinPixels: 2设置点在屏幕上的最小像素半径防止缩小地图时点消失pointRadiusScale: 2000半径的全局缩放因子用于把地理尺度映射到像素getPointRadius: f 11 - f.properties.scalerank根据属性scalerank动态决定半径——scalerank 越小机场越重要半径越大getFillColor: [200, 0, 80, 180]RGBA 颜色最后一个分量 180 为半透明pickable: trueautoHighlight: true开启拾取与悬停高亮onClick点击机场时用alert弹出名称与缩写properties.name/properties.abbrev被注释的beforeId: waterway-label仅在 interleaved 模式下生效用于把 deck.gl 图层插入到 Mapbox 样式图层waterway-label之前让机场点渲染在地图文字标签下方。5. ArcLayer伦敦出发的弧形航线new ArcLayer({ id: arcs, data: AIR_PORTS, dataTransform: d d.features.filter(f f.properties.scalerank 4), // Styles getSourcePosition: f [-0.4531566, 51.4709959], // London getTargetPosition: f f.geometry.coordinates, getSourceColor: [0, 128, 200], getTargetColor: [200, 0, 80], getWidth: 1 })与 GeoJsonLayer 共享同一份机场数据但通过dataTransform在渲染前过滤出scalerank 4的重要机场约几十个避免航线过于密集起点固定为伦敦坐标终点为各机场坐标起点蓝色、终点红色形成视觉上的方向感。getWidth: 1为像素单位的线宽。6. index.html全屏地图容器index.html 本身非常简洁但有一个关键点地图容器使用position: fixed铺满视口并在 body 末尾以 ES Module 方式加载app.jsdiv idmap/div script typemodule srcapp.js/scripttypemodule是 Vite 开发模式下浏览器原生 ES Module 加载的基础无需任何打包即可运行 import 语法。源码深潜MapboxOverlay 的两种渲染模式MapboxOverlay的实现位于 modules/mapbox/src/mapbox-overlay.ts其核心设计是屏蔽 Deck 与地图相关的大部分 propwidth/height/gl/parent/canvas/viewState/controller 等由 overlay 内部从 mapbox-gl 实例推导。构造函数通过interleaved决定走哪条渲染路径mapbox-overlay.tsconstructor(props: MapboxOverlayProps) { const {interleaved false} props; this._interleaved interleaved; this._props this.filterProps(props); }Overlaid 模式默认独立 canvas 叠加当interleaved为 false 时_onAddOverlaidmapbox-overlay.ts会创建一个绝对定位的div容器设置pointerEvents: none避免遮挡地图交互在该容器内new Deck({...})创建独立 WebGL 上下文监听地图的resize、render、mousedown/drag*/click/dblclick/mousemove等事件把相机状态和鼠标事件同步给 Deck。这种模式的好处是 deck.gl 图层渲染在独立的 canvas上与 Mapbox 的控件NavigationControl、Popup和插件mapbox-gl-draw、路线导航等天然兼容是官方推荐的通用方案。代价是 deck.gl 图层与 Mapbox 矢量图层之间没有严格的遮挡关系无法精确地让 deck.gl 表面穿插在地图文字标签之下。Interleaved 模式共享 WebGL2 上下文当interleaved: true时_onAddInterleavedmapbox-overlay.ts从底图内部取出 WebGL 上下文const gl: WebGL2RenderingContext map.painter.context.gl;然后让 Deck 直接复用这个上下文把 deck.gl 图层作为自定义图层插入 Mapbox 的样式图层栈。由于是共享上下文deck.gl 图层与底图图层可以逐层交错、正确遮挡——例如让弧线渲染在道路之下、让机场点渲染在水系标签之下。它的前提是 WebGL2 与mapbox-gl2.13MapLibre 亦有对应支持并且会丢弃useDevicePixels底图拥有 canvas 尺寸与 DPR 的控制权见 mapbox-overlay.ts 中filterProps的注释。相机同步viewState 的推导无论哪种模式deck.gl 的相机都必须与 Mapbox 相机严格一致。deck-utils.ts 的getViewState从地图实例同步全部相机参数const viewState { longitude: ((lng 540) % 360) - 180, // 处理反经线附近越界 latitude: lat, zoom: map.getZoom(), bearing: map.getBearing(), pitch: map.getPitch(), padding: map.getPadding(), repeat: map.getRenderWorldCopies() };值得一提的细节当底图开启地形map.getTerrain()时centerCameraOnTerrain会根据自由相机位置反推海拔把viewState.position校准到地形表面保证 deck.gl 图层与地形严格贴合deck-utils.ts。此外getDefaultView会根据地图投影自动选择MapViewmercator或GlobeViewglobe 投影即马卡托投影下用平面视图、地球投影下自动切换为球体视图deck-utils.ts。beforeId 与图层分组deck.gl 如何插入 Mapbox 图层栈interleaved 模式下beforeId的实现依赖 resolve-layer-groups.ts。deck.gl 会把所有图层按beforeId或slot分组每组对应一个 Mapbox 自定义图层export function getLayerGroupId(layer) { if (layer.props.beforeId) { return deck-layer-group-before:${layer.props.beforeId}; } else if (layer.props.slot) { return deck-layer-group-slot:${layer.props.slot}; } return deck-layer-group-last; }随后resolveLayerGroups执行三步resolve-layer-groups.ts清理删除已不存在的图层分组map.removeLayer插入为缺失的分组创建MapboxLayerGroup并用map.addLayer(newGroup, layer.props.beforeId)插入到指定位置排序读取map.style._order检查分组实际位置必要时用map.moveLayer把分组移动到beforeId之前。这就是示例中注释beforeId: waterway-label生效的底层链路deck.gl 先注册位于 waterway-label 之前的分组底图在每帧渲染到该位置时通过_customRender触发 deck.gl 绘制见 deck-utils.ts 的deck.props._customRender包装它调用map.triggerRepaint()让底图重绘并把绘制交给MapboxLayerGroup。事件转发Mapbox 鼠标事件 → deck.gl 交互overlaid 模式不需要处理 interleaved 的图层插入但必须解决交互问题由于 deck.gl canvas 设置了pointerEvents: none鼠标事件会落在 Mapbox 容器上。_handleMouseEventmapbox-overlay.ts把 Mapbox 事件翻译成 mjolnir.js 手势事件再喂给 Deckmousedown→deck._onPointerDown记录按下点dragstart/drag/dragend→panstart/panmove/panenddrag 事件不含point字段需用按下点 位移增量推算click/dblclick→ 带tapCount的click事件mousemove/mouseout→pointermove/pointerleave。这正是示例中pickable、autoHighlight、onClick能够工作的前提——点击机场弹出 alert 的背后是 Mapbox 的click事件被转发为 deck.gl 的拾取查询。三种集成模式如何选型使用 Mapboxdocs/developer-guide/base-maps/using-with-mapbox.md 将 deck.gl 与 Mapbox 的集成归纳为三种模式本示例的MapboxOverlay覆盖前两种模式实现方式适用场景限制InterleavedMapboxOverlayinterleaved: true需要 deck.gl 图层与底图图层精确交错遮挡如表面渲染在文字标签下、3D 物体相互遮挡需要 WebGL2 与 mapbox-gl 2.13不能使用部分 Mapbox 控件OverlaidMapboxOverlay默认无需精确交错但要使用 Mapbox 控件与插件NavigationControl、Popup、draw 等deck.gl 与底图图层无严格遮挡关系Reverse controlled纯 JS 下用 deck.gl 顶层控制需要自定义指针输入、多视图或地图不满屏的场景不能使用 Mapbox 控件需改用deck.gl/widgets纯 JS 下实现较繁琐纯 JS 场景下官方推荐MapboxOverlay因为它可以在两种模式间一键切换interleaved: true/false且天然兼容 Mapbox 生态。React 用户若选择 interleaved/overlaid可通过 react-map-gl 的useControl挂载MapboxOverlayreverse controlled 模式则需让DeckGL作为根组件、Map作为子组件。生产构建与常见坑运行npm run build后Vite 会把app.js连同所有依赖打包到dist/目录部署到任意静态服务器即可。生产环境两个高频问题token 泄露与注入define是构建期替换token 会被直接写进产物 bundle。生产环境建议通过运行时环境注入或服务端代理鉴权避免把 token 硬编码进仓库本地开发则可用环境变量方式。interleaved 报 WebGL 兼容性警告如果底图库不支持 WebGL2_onAddInterleaved会通过log.warn输出 Incompatible basemap library 提示mapbox-overlay.ts此时应降级到 overlaid 模式。小结从 README 的 5 个文件出发本文完整还原了 deck.gl × Mapbox 纯 JS 集成的全链路环境变量注入 token → Vite 启动/构建 → mapboxgl.Map 初始化 → MapboxOverlay 挂载 → GeoJsonLayer/ArcLayer 配置 → 拾取交互并向上追溯源码解释了MapboxOverlay如何通过IControl接口融入 Mapbox、如何在 interleaved/overlaid 两种模式下分别复用共享 WebGL2 上下文与创建独立 canvas、如何用resolveLayerGroups把图层按beforeId插入底图图层栈、以及如何把 Mapbox 鼠标事件翻译成 deck.gl 手势事件。掌握这些之后你可以自由替换图层与数据源把任意 deck.gl 可视化叠加到 Mapbox 底图之上。【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
deck.gl × Mapbox 纯 JavaScript 集成实战：从 Vite 示例到 MapboxOverlay 源码级解析
deck.gl × Mapbox 纯 JavaScript 集成实战从 Vite 示例到 MapboxOverlay 源码级解析【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl本篇技术指南以 deck.gl 仓库中的 pure-js/mapbox 示例 为核心骨架完整讲解如何用原生 JavaScript 与 Vite 将 deck.gl 图层叠加到 Mapbox GL 地图上从获取 Access Token、安装依赖、启动开发服务器到逐行拆解app.js中 GeoJsonLayer 与 ArcLayer 的配置并深入deck.gl/mapbox模块源码揭示MapboxOverlay实现相机同步、图层插入与事件转发的底层机制。读完后你将能独立搭建一个deck.gl 数据图层 Mapbox 底图的纯 JS 工程并理解 interleaved / overlaid 两种渲染模式的区别与选型。示例定位纯 JS Vite 的最小可运行工程示例位于仓库的 examples/get-started/pure-js/mapbox 目录它不依赖 React直接使用原生 JavaScript 通过mapbox-gl创建地图再借助deck.gl/mapbox的MapboxOverlay把 deck.gl 图层叠加上去。整个工程只有 5 个文件examples/get-started/pure-js/mapbox/ ├── app.js # 应用主逻辑地图初始化 deck.gl 图层 ├── index.html # 页面骨架与地图容器 ├── package.json # 依赖与 npm 脚本 ├── vite.config.js # Vite 配置注入环境变量 └── README.md # 运行说明根据 package.json工程依赖如下deck.gl/core^9.0.0deck.gl 运行时核心deck.gl/layers^9.0.0提供 GeoJsonLayer、ArcLayer 等内置图层deck.gl/mapbox^9.0.0提供MapboxOverlay负责与 mapbox-gl 深度集成mapbox-gl^3.0.0Mapbox 底图库vite^7.3.3devDependency开发服务器与打包器。示例 README 明确说明使用 Vite 负责打包与服务这是纯 JS 场景下最轻量的工程化方案零配置、按需编译、开发热更新生产构建输出可直接部署的静态资源。运行前置获取并注入 Mapbox Access TokenMapbox 的地图瓦片服务要求请求方携带 Access Token 以标识身份。官方集成指南 使用 Mapboxdocs/developer-guide/base-maps/using-with-mapbox.md 指出需要先在 Mapbox 官网注册并申请 token。README 给出了两种注入 token 的方式方式一设置环境变量推荐export MapboxAccessTokenmapbox_access_token在 vite.config.js 中Vite 通过define把环境变量在构建期替换进代码export default { define: { process.env.MapboxAccessToken: JSON.stringify(process.env.MapboxAccessToken) } };而 app.js 里读取的就是这个变量// Set your Mapbox token here or via environment variable const MAPBOX_TOKEN process.env.MapboxAccessToken; // eslint-disable-linedefine属于 Vite 的构建期常量替换这意味着开发服务器启动前环境变量就必须已经导出如果启动后再修改环境变量需要重启npm start才会生效。方式二直接在app.js中硬编码例如把第 15 行改为const MAPBOX_TOKEN mapbox_access_token;作为对比使用 react-map-gl 时还可以通过 URL 参数?access_tokenTOKEN或Map mapboxAccessToken{TOKEN} /prop 传入详见 使用 Mapbox 的 Mapbox Token 一节。注意Mapbox GL JS 自 2.0 起采用专有许可证即使不加载 Mapbox 服务器的瓦片也需要账户与 token如果希望完全脱离 Mapbox 服务可考虑 MapLibre GL JS见 使用 MapLibre或 mapbox-gl v1.13但后者不支持 interleaved 渲染。安装依赖与启动命令在示例目录下安装依赖npm 与 yarn 均可npm install # or yarn随后即可使用 package.json 中定义的脚本命令作用npm start开发模式启动 Vite 开发服务器并自动打开浏览器支持热更新对应vite --opennpm run start-local使用仓库根目录的 vite.config.local.mjs 启动用于在 monorepo 中直接引用本地源码模块调试npm run build生产构建生成最终 bundle 并写入磁盘对应vite buildnpm run start-local是 deck.gl monorepo 特有的脚本它让示例直接链接仓库内的本地模块源码而非 npm 上的发布包方便开发者调试 deck.gl 本身的改动普通使用者运行npm start即可。逐段拆解 app.js地图 图层 交互1. 导入与数据源app.js 开头的导入是本示例的核心依赖import {MapboxOverlay as DeckOverlay} from deck.gl/mapbox; import {GeoJsonLayer, ArcLayer} from deck.gl/layers; import mapboxgl from mapbox-gl; import mapbox-gl/dist/mapbox-gl.css;把MapboxOverlay别名成DeckOverlay仅为语义清晰它本质上是一个实现了 MapboxIControl接口的控件。数据源使用 Natural Earth 提供的全球机场 GeoJSON通过 geojson.xyz 的 CDN 分发覆盖全球约数千个机场点const AIR_PORTS https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_airports.geojson;2. 初始化 Mapbox 地图const map new mapboxgl.Map({ container: map, style: mapbox://styles/mapbox/light-v9, accessToken: MAPBOX_TOKEN, center: [0.45, 51.47], zoom: 4, bearing: 0, pitch: 30 });container: map对应 index.html 中的div idmap/div该容器通过 CSS 铺满整个视口地图中心设为伦敦经度 0.45、纬度 51.47初始缩放级别 4俯仰角 30°——倾斜视角正是后文 ArcLayer 弧形航线的最佳展示角度。3. 创建 MapboxOverlay 并挂载const deckOverlay new DeckOverlay({ // interleaved: true, layers: [ ... ] }); map.addControl(deckOverlay); map.addControl(new mapboxgl.NavigationControl());map.addControl(deckOverlay)把 overlay 作为 Mapbox 控件注册进地图MapboxOverlay的默认控件位置是top-left源码见 mapbox-overlay.ts 的getDefaultPosition()。代码中interleaved: true被注释掉因此默认走 overlaid 模式下一节会详述这两种模式的差异。注意示例没有把创建 overlay 放在map.once(load)回调里overlaid 模式下MapboxOverlay会在自己创建的独立 canvas 上渲染与底图加载状态解耦而 interleaved 模式需要共享底图的 WebGL2 上下文与样式图层栈官方文档示例using-with-mapbox.md通常放在map.once(load)中执行。4. GeoJsonLayer机场点位可视化new GeoJsonLayer({ id: airports, data: AIR_PORTS, // Styles filled: true, pointRadiusMinPixels: 2, pointRadiusScale: 2000, getPointRadius: f 11 - f.properties.scalerank, getFillColor: [200, 0, 80, 180], // Interactive props pickable: true, autoHighlight: true, onClick: info info.object alert(${info.object.properties.name} (${info.object.properties.absprev})) // beforeId: waterway-label // In interleaved mode render the layer under map labels })参数解读pointRadiusMinPixels: 2设置点在屏幕上的最小像素半径防止缩小地图时点消失pointRadiusScale: 2000半径的全局缩放因子用于把地理尺度映射到像素getPointRadius: f 11 - f.properties.scalerank根据属性scalerank动态决定半径——scalerank 越小机场越重要半径越大getFillColor: [200, 0, 80, 180]RGBA 颜色最后一个分量 180 为半透明pickable: trueautoHighlight: true开启拾取与悬停高亮onClick点击机场时用alert弹出名称与缩写properties.name/properties.abbrev被注释的beforeId: waterway-label仅在 interleaved 模式下生效用于把 deck.gl 图层插入到 Mapbox 样式图层waterway-label之前让机场点渲染在地图文字标签下方。5. ArcLayer伦敦出发的弧形航线new ArcLayer({ id: arcs, data: AIR_PORTS, dataTransform: d d.features.filter(f f.properties.scalerank 4), // Styles getSourcePosition: f [-0.4531566, 51.4709959], // London getTargetPosition: f f.geometry.coordinates, getSourceColor: [0, 128, 200], getTargetColor: [200, 0, 80], getWidth: 1 })与 GeoJsonLayer 共享同一份机场数据但通过dataTransform在渲染前过滤出scalerank 4的重要机场约几十个避免航线过于密集起点固定为伦敦坐标终点为各机场坐标起点蓝色、终点红色形成视觉上的方向感。getWidth: 1为像素单位的线宽。6. index.html全屏地图容器index.html 本身非常简洁但有一个关键点地图容器使用position: fixed铺满视口并在 body 末尾以 ES Module 方式加载app.jsdiv idmap/div script typemodule srcapp.js/scripttypemodule是 Vite 开发模式下浏览器原生 ES Module 加载的基础无需任何打包即可运行 import 语法。源码深潜MapboxOverlay 的两种渲染模式MapboxOverlay的实现位于 modules/mapbox/src/mapbox-overlay.ts其核心设计是屏蔽 Deck 与地图相关的大部分 propwidth/height/gl/parent/canvas/viewState/controller 等由 overlay 内部从 mapbox-gl 实例推导。构造函数通过interleaved决定走哪条渲染路径mapbox-overlay.tsconstructor(props: MapboxOverlayProps) { const {interleaved false} props; this._interleaved interleaved; this._props this.filterProps(props); }Overlaid 模式默认独立 canvas 叠加当interleaved为 false 时_onAddOverlaidmapbox-overlay.ts会创建一个绝对定位的div容器设置pointerEvents: none避免遮挡地图交互在该容器内new Deck({...})创建独立 WebGL 上下文监听地图的resize、render、mousedown/drag*/click/dblclick/mousemove等事件把相机状态和鼠标事件同步给 Deck。这种模式的好处是 deck.gl 图层渲染在独立的 canvas上与 Mapbox 的控件NavigationControl、Popup和插件mapbox-gl-draw、路线导航等天然兼容是官方推荐的通用方案。代价是 deck.gl 图层与 Mapbox 矢量图层之间没有严格的遮挡关系无法精确地让 deck.gl 表面穿插在地图文字标签之下。Interleaved 模式共享 WebGL2 上下文当interleaved: true时_onAddInterleavedmapbox-overlay.ts从底图内部取出 WebGL 上下文const gl: WebGL2RenderingContext map.painter.context.gl;然后让 Deck 直接复用这个上下文把 deck.gl 图层作为自定义图层插入 Mapbox 的样式图层栈。由于是共享上下文deck.gl 图层与底图图层可以逐层交错、正确遮挡——例如让弧线渲染在道路之下、让机场点渲染在水系标签之下。它的前提是 WebGL2 与mapbox-gl2.13MapLibre 亦有对应支持并且会丢弃useDevicePixels底图拥有 canvas 尺寸与 DPR 的控制权见 mapbox-overlay.ts 中filterProps的注释。相机同步viewState 的推导无论哪种模式deck.gl 的相机都必须与 Mapbox 相机严格一致。deck-utils.ts 的getViewState从地图实例同步全部相机参数const viewState { longitude: ((lng 540) % 360) - 180, // 处理反经线附近越界 latitude: lat, zoom: map.getZoom(), bearing: map.getBearing(), pitch: map.getPitch(), padding: map.getPadding(), repeat: map.getRenderWorldCopies() };值得一提的细节当底图开启地形map.getTerrain()时centerCameraOnTerrain会根据自由相机位置反推海拔把viewState.position校准到地形表面保证 deck.gl 图层与地形严格贴合deck-utils.ts。此外getDefaultView会根据地图投影自动选择MapViewmercator或GlobeViewglobe 投影即马卡托投影下用平面视图、地球投影下自动切换为球体视图deck-utils.ts。beforeId 与图层分组deck.gl 如何插入 Mapbox 图层栈interleaved 模式下beforeId的实现依赖 resolve-layer-groups.ts。deck.gl 会把所有图层按beforeId或slot分组每组对应一个 Mapbox 自定义图层export function getLayerGroupId(layer) { if (layer.props.beforeId) { return deck-layer-group-before:${layer.props.beforeId}; } else if (layer.props.slot) { return deck-layer-group-slot:${layer.props.slot}; } return deck-layer-group-last; }随后resolveLayerGroups执行三步resolve-layer-groups.ts清理删除已不存在的图层分组map.removeLayer插入为缺失的分组创建MapboxLayerGroup并用map.addLayer(newGroup, layer.props.beforeId)插入到指定位置排序读取map.style._order检查分组实际位置必要时用map.moveLayer把分组移动到beforeId之前。这就是示例中注释beforeId: waterway-label生效的底层链路deck.gl 先注册位于 waterway-label 之前的分组底图在每帧渲染到该位置时通过_customRender触发 deck.gl 绘制见 deck-utils.ts 的deck.props._customRender包装它调用map.triggerRepaint()让底图重绘并把绘制交给MapboxLayerGroup。事件转发Mapbox 鼠标事件 → deck.gl 交互overlaid 模式不需要处理 interleaved 的图层插入但必须解决交互问题由于 deck.gl canvas 设置了pointerEvents: none鼠标事件会落在 Mapbox 容器上。_handleMouseEventmapbox-overlay.ts把 Mapbox 事件翻译成 mjolnir.js 手势事件再喂给 Deckmousedown→deck._onPointerDown记录按下点dragstart/drag/dragend→panstart/panmove/panenddrag 事件不含point字段需用按下点 位移增量推算click/dblclick→ 带tapCount的click事件mousemove/mouseout→pointermove/pointerleave。这正是示例中pickable、autoHighlight、onClick能够工作的前提——点击机场弹出 alert 的背后是 Mapbox 的click事件被转发为 deck.gl 的拾取查询。三种集成模式如何选型使用 Mapboxdocs/developer-guide/base-maps/using-with-mapbox.md 将 deck.gl 与 Mapbox 的集成归纳为三种模式本示例的MapboxOverlay覆盖前两种模式实现方式适用场景限制InterleavedMapboxOverlayinterleaved: true需要 deck.gl 图层与底图图层精确交错遮挡如表面渲染在文字标签下、3D 物体相互遮挡需要 WebGL2 与 mapbox-gl 2.13不能使用部分 Mapbox 控件OverlaidMapboxOverlay默认无需精确交错但要使用 Mapbox 控件与插件NavigationControl、Popup、draw 等deck.gl 与底图图层无严格遮挡关系Reverse controlled纯 JS 下用 deck.gl 顶层控制需要自定义指针输入、多视图或地图不满屏的场景不能使用 Mapbox 控件需改用deck.gl/widgets纯 JS 下实现较繁琐纯 JS 场景下官方推荐MapboxOverlay因为它可以在两种模式间一键切换interleaved: true/false且天然兼容 Mapbox 生态。React 用户若选择 interleaved/overlaid可通过 react-map-gl 的useControl挂载MapboxOverlayreverse controlled 模式则需让DeckGL作为根组件、Map作为子组件。生产构建与常见坑运行npm run build后Vite 会把app.js连同所有依赖打包到dist/目录部署到任意静态服务器即可。生产环境两个高频问题token 泄露与注入define是构建期替换token 会被直接写进产物 bundle。生产环境建议通过运行时环境注入或服务端代理鉴权避免把 token 硬编码进仓库本地开发则可用环境变量方式。interleaved 报 WebGL 兼容性警告如果底图库不支持 WebGL2_onAddInterleaved会通过log.warn输出 Incompatible basemap library 提示mapbox-overlay.ts此时应降级到 overlaid 模式。小结从 README 的 5 个文件出发本文完整还原了 deck.gl × Mapbox 纯 JS 集成的全链路环境变量注入 token → Vite 启动/构建 → mapboxgl.Map 初始化 → MapboxOverlay 挂载 → GeoJsonLayer/ArcLayer 配置 → 拾取交互并向上追溯源码解释了MapboxOverlay如何通过IControl接口融入 Mapbox、如何在 interleaved/overlaid 两种模式下分别复用共享 WebGL2 上下文与创建独立 canvas、如何用resolveLayerGroups把图层按beforeId插入底图图层栈、以及如何把 Mapbox 鼠标事件翻译成 deck.gl 手势事件。掌握这些之后你可以自由替换图层与数据源把任意 deck.gl 可视化叠加到 Mapbox 底图之上。【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
