简介围绕 mapbox-gl.js v2.13.0 的扩展实现以切片地图服务加载与绘图控件集成为核心为需要在 Web 端适配多坐标系的 GIS 开发者提供一套可直接复用的方案。扩展支持 4326、3857、4490 三类常用坐标系关闭 token 请求便于本地调试和离线运行演示示例覆盖 4326 与 3857 坐标系绘图控件支持点、线、面、矩形、圆以及编辑、删除等交互。压缩包共 11 个文件整体约 601KB以 6 个 JavaScript 文件处理坐标适配、底图配置与绘图逻辑2 个 html 文件作为演示入口2 个 css 负责地图与绘图控件样式1 个 json 文件提供测试数据结构紧凑便于按需修改。资源从原始矢量数据分层、样式设计、矢量切片缓存到前端可视化与功能应用梳理了矢量切片落地的完整链路适合刚接触 Mapbox GL 或正在做地图可视化项目的开发者参考。示例中还包含武汉地区底图配置可配合已有切片服务快速验证 4326 与 3857 坐标系加载目前已有 2254 人学习下载对地图开发入门与扩展都有不错的参考价值。 最近在做一个地理数据可视化项目要用 mapbox-gl.js v2.13.0 把不同来源的切片地图服务全部统一到一张图上同时还要支持在线绘图。数据源里既有常见的 WGS84 经纬度切片也有 Web 墨卡托切片还有不少标着 CGCS2000 的4490坐标系数据。原本以为只是简单调用addSource就能解决结果第一版加载出来就是花屏、错位、叠不齐折腾了几天才彻底搞清楚 4326、3857、4490 三种坐标系在 Mapbox GL 里的脾气。这篇笔记把这套实现完整记录下来包括坐标系底层差异、切片服务加载的3种写法、绘图控件集成和排查经验。适合正在做 GIS 前端、Web 地图开发或者需要接国产化地理数据的同学收藏。1. 坐标系不是玄学先搞清楚这3个EPSG1.1 4326、3857、4490 的核心差异很多前端同学对坐标系的理解停留在“改了 URL 就能用”但实际上切片服务能不能正确显示核心就在坐标系。我把三个坐标系最关键的参数整理成了对照表EPSG编号名称椭球体坐标单位切片组织方式典型应用场景4326WGS84 经纬度WGS84度经纬度直投网格GPS数据、全球底图、OGC标准服务3857Web墨卡托投影WGS84米全球正方形网格互联网地图、Mapbox、Google Maps4490CGCS2000 经纬度GRS80度经纬度直投网格国内测绘成果、国土/规划数据这里最容易混淆的是 4326 和 4490。两者都是经纬度坐标单位也都是度视觉上几乎看不出来区别。但它们使用的椭球体不同4326 基于 WGS84 椭球4490 基于 GRS80 椭球。因为 GRS80 和 WGS84 在长半轴、扁率上差异极小所以在普通前端展示中同一地点的经纬度差只有厘米到分米级肉眼完全感知不到。但在测绘级别、地籍数据、高精度不动产图层叠加时这个差异必须用转换参数处理。3857 则是另一种思路。它把地球做成一个正方形平面用米作为单位避免了经纬度在高纬度地区“变形到没法看”的问题互联网地图几乎全用它。Mapbox GL 内部渲染时也默认基于 3857 投影这是所有坐标系处理问题的根源。1.2 为什么 Mapbox GL 默认只认 3857Mapbox GL JS 从底层设计上就把 Web Mercator 作为默认投影基准地图的瓦片网格、相机坐标、裁剪范围全部基于 3857 计算。当你加载一个自定义栅格源时它会默认把瓦片 URL 里的{z}/{x}/{y}理解为“3857 网络下的瓦片行列号”。换句话说如果你的服务端发布的切片是 4326 经纬度直投网格或者 4490 网格但前端直接用tiles: [xxx/{z}/{x}/{y}.png]这种方式加载Mapbox GL 会把你给的瓦片硬塞到 3857 网格里。低缩放级别全球范围还能勉强看个轮廓放大到城市级别就会明显发现瓦片错位、拉伸、拼接不整齐因为两者的瓦片边界本来就不对应。一句话总结不是坐标系有毛病而是 Mapbox GL v2 没有给你换投影的入口。v3 版本才开始支持setProjection自定义投影v2.13.0 这个版本里必须用别的手段解决。2. 环境准备v2.13.0 依赖与最小可运行地图2.1 引入依赖和 Token 配置我用的是 npm 方式项目基于 Vite 搭建安装命令npm install mapbox-gl2.13.0代码里引入样式和 JSimport mapboxgl from mapbox-gl; import mapbox-gl/dist/mapbox-gl.css; mapboxgl.accessToken 你的token;这里有个特别容易踩的坑Mapbox GL v2 以上版本强制要求设置accessToken否则地图只显示一个水印 logo而且底图无法加载。如果你用的是离线环境也需要在初始化配置里把accessToken设置为任意非空字符串再配合自定义离线源使用否则会直接报错。如果是纯 HTML 页面也可以走 CDN 方式link hrefhttps://api.mapbox.com/mapbox-gl-js/v2.13.0/mapbox-gl.css relstylesheet script srchttps://api.mapbox.com/mapbox-gl-js/v2.13.0/mapbox-gl.js/script注意 v2.13.0 的 CDN 地址和 npm 包版本必须一致不然容易出现 API 不匹配的兼容问题。2.2 初始化一张干净的地图初始化代码如下const map new mapboxgl.Map({ container: map, style: { version: 8, sources: {}, layers: [] }, center: [116.391, 39.907], zoom: 5, attributionControl: false });我没有直接使用 Mapbox 官方的在线底图样式而是自定义一个空 style原因是后面要叠加多个不同来源的切片服务官方样式里的mapbox://源在离线或私有化部署场景下不一定能访问直接自己搭更可控。初始化成功之后地图上应该是一片空白背景鼠标拖拽缩放正常。接下来开始逐个叠加切片服务。3. 加载3857切片服务标准姿势与参数细节3.1 栅格源配置核心参数3857 切片是最好的情况因为 Mapbox GL 原生就支持只需要配置一个 raster sourcemap.addSource(base3857, { type: raster, tiles: [ https://your-server.com/tiles/{z}/{x}/{y}.png ], tileSize: 256, minzoom: 0, maxzoom: 18, attribution: 数据来源 }); map.addLayer({ id: base3857-layer, type: raster, source: base3857 });这里面的参数里tileSize是重灾区。很多切片服务器用的是 512 像素的瓦片但 Mapbox GL 默认按 256 去计算缩放级别如果你的瓦片实际上是 512必须显式设置tileSize: 512否则地图会显得特别“虚”字体和线划都是模糊的。scheme参数也很关键。默认是xyz瓦片 Y 轴从左上角开始往下递增如果服务端用的是 TMS 规范从左下角开始必须加一个scheme: tms配置否则加载出来的图上下颠倒或者南北方向错乱。map.addSource(base3857, { type: raster, tiles: [.../{z}/{x}/{y}.png], scheme: tms });3.2 实测中容易翻车的位置加载 3857 切片时我遇到过三个典型问题提前说下第一跨域问题。切片服务器如果没有配置 CORS浏览器控制台会报No Access-Control-Allow-Origin header。在开发环境可以用 Vite 的代理解决生产环境必须让服务端加 CORS 头或者走同域反向代理。第二瓦片 URL 里不能拼接 token 关键词冲突。有的后端服务会把{z}{x}{y}当成自己平台的模板变量处理导致请求 404。建议在拼接 URL 时确认服务端对花括号模板变量的支持情况或者用transformRequest统一加工。第三bounds参数不设会有多余请求。如果这个 3857 切片服务只覆盖某个城市最好加上bounds: [120.1, 30.2, 122.3, 32.1]告诉 Mapbox 只在指定范围内请求瓦片不然用户一缩放到全国范围控制台里会刷一堆 404 请求影响性能。4. 加载4326和4490切片服务两条路线自己选4.1 路线一服务端统一重投影为3857这是我在生产项目里最推荐的方式。不管原始数据是 4326、4490 还是北京54、西安80统一在服务端处理好发布成 3857 切片前端就永远只需要面对一种坐标系。GeoServer 里操作路径是Layer Preview 里选好图层后切换到 Tile Caching 选项卡新增一个 Gridset选择 EPSG:3857然后重新切片。GeoWebCache 也会自动生成EPSG:3857对应的瓦片 URLhttps://your-server.com/geoserver/gwc/service/wmts?layerxxxtilematrixsetEPSG:3857...tilematrix{z}tilerow{y}tilecol{x}这样前端代码完全可以复用第3章的 3857 加载逻辑只是 URL 里的参数名从{x}{y}{z}变成了 WMTS 风格。需要说明这不是 Mapbox 的行为而是让你把瓦片服务“喂”到它认识的模式里。这个方案的优势非常明显前端逻辑统一不需要为不同坐标系写特殊情况Mapbox 的性能最优瓦片范围匹配不会有额外无谓请求绘图控件坐标天然统一不会有坐标系切换的认知负担缺点是需要控制服务端的切片策略如果数据源是外部提供的静态 4326 瓦片不方便重新发布那就只能走路线二。4.2 路线二前端做瓦片坐标换算近似加载4326/4490有些场景下你拿到的外部服务就是 4326 或 4490 的固定瓦片比如天地图、某些省市发布的历史数据切片不允许你重新切。这时必须在前端做坐标换算。核心原理是Mapbox GL 请求瓦片时URL 里的{z}{x}{y}是基于 3857 网格的。我们可以用transformRequest拦截请求把 3857 瓦片号换算成 4326 经纬度直投瓦片号再替换 URL 请求参数。我贴一段项目里实测可用的核心代码// 3857瓦片行列号转经纬度 function tileToLonLat(x, y, z) { const n Math.PI - (2 * Math.PI * y) / Math.pow(2, z); const lon (x / Math.pow(2, z)) * 360 - 180; const lat (180 / Math.PI) * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n))); return [lon, lat]; } // 经纬度转EPSG:4326 WMTS瓦片行列号 function lonLatToTile4326(lon, lat, z) { // 根据服务端gridset调整常见的是TileMatrix 0级为2列1行 const cols Math.pow(2, z 1); const rows Math.pow(2, z); const x Math.floor((lon 180) / 360 * cols); const y Math.floor((90 - lat) / 180 * rows); return { x, y, z }; } map.addSource(crs4326source, { type: raster, tiles: [ https://your-server.com/wmts?...TILEMATRIX{z}TILEROW{y}TILECOL{x} ], tileSize: 256, transformRequest: (url, resourceType) { if (resourceType ! Tile) { return { url }; } // 从URL里解析Mapbox请求的3857瓦片坐标 const match url.match(/TILEMATRIX(\d)TILEROW(\d)TILECOL(\d)/); if (!match) { return { url }; } const zM parseInt(match[1], 10); const yM parseInt(match[2], 10); const xM parseInt(match[3], 10); // 将3857瓦片坐标转为经纬度 const [lon, lat] tileToLonLat(xM, yM, zM); // 这里将z4326设置为zM 1只是我项目里的匹配方法要按你的gridset调整 const z4326 zM 1; const tile lonLatToTile4326(lon, lat, z4326); const newUrl url .replace(/TILEMATRIX\d/, TILEMATRIX${tile.z}) .replace(/TILEROW\d/, TILEROW${tile.y}) .replace(/TILECOL\d/, TILECOL${tile.x}); return { url: newUrl }; } });这里有两个点特别提醒第一个是z4326的取值没有统一标准完全取决于服务端 gridset 怎么定义。有的服务端 EPSG:4326 grid 从 0 级开始就是 2 列 1 行有的封装成 XYZ 风格后行列数和 3857 的关系又不一样。我建议先手动请求几个服务端瓦片把返回图片和对应经纬度范围对照确认映射公式后再写进transformRequest。第二个是这种映射方式本质上是“用瓦片中心点经纬度去找对应瓦片”当地图缩放级别较低、单个瓦片覆盖经纬度范围较大时边缘区域可能会差出几百米甚至几公里。所以这个方案只适合做展示不适合做高精度量测和空间分析。4.3 4490坐标系加载的特别提醒4490 的瓦片网格原则上和 4326 一样都是经纬度直投所以上面的lonLatToTile4326可以直接复用。实际项目里我也确实见过不少直接把 4490 切片当 4326 加载的案例因为视觉上几乎无差别。但有一个点必须注意如果你加载了 4490 切片同时又在地图上做标记、绘图最后把数据存库落库前端拿到的坐标永远是 Mapbox 内部用的 WGS84 经纬度不是 CGCS2000。需要做转换可以用 proj4js 定义import proj4 from proj4; proj4.defs(EPSG:4326, projlonglat datumWGS84 no_defs); proj4.defs(EPSG:4490, projlonglat ellpsGRS80 no_defs); // 从WGS84转到CGCS2000 const [lon4490, lat4490] proj4(EPSG:4326, EPSG:4490, [116.391, 39.907]);转换后的经纬度和原始值差异很小但走完这一道流程至少数据属性上是严谨的。如果项目要求更高精度需要用到控制点七参数或者格网改正那就不是前端范畴的事了得交给服务端 GIS 处理。5. 绘图控件叠加绘制能力5.1 接入 mapbox/mapbox-gl-draw绘图控件我直接用的 Mapbox 官方插件mapbox/mapbox-gl-draw。v2.13.0 的 Mapbox GL 对应插件版本用的是 1.4.x装太高版本容易出现 API 不兼容。npm install mapbox/mapbox-gl-draw1.4.3CSS 也需要引入import mapbox/mapbox-gl-draw/dist/mapbox-gl-draw.css; import MapboxDraw from mapbox/mapbox-gl-draw;初始化代码const draw new MapboxDraw({ displayControlsDefault: false, controls: { point: true, line_string: true, polygon: true, trash: true }, defaultMode: simple_select }); map.addControl(draw, top-left);加载完成后地图左上角会出现点、线、面、删除四个按钮。5.2 绘制数据导出与坐标系转换绘图完成后拿数据是通过事件map.on(draw.create, (e) { const feature e.features[0]; console.log(feature.geometry.coordinates); // 这里拿到的坐标是WGS84经纬度 });这里必须强调一个容易忽视的点不管你的底图是 3857 切片还是 4326/4490 切片Mapbox GL 内部所有图形数据的坐标基准都是 WGS84 经纬度。也就是说用户在城市图上画一个地块控件返回的坐标可以直接扔进 GeoJSON 里但如果你的业务库要求存储 4490 坐标系就需要在保存前用上一节 proj4 的转换逻辑逐点处理。多边形转换的伪代码function convertGeometry(geometry, fromCrs, toCrs) { if (geometry.type Point) { return { type: Point, coordinates: proj4(fromCrs, toCrs, geometry.coordinates) }; } if (geometry.type LineString || geometry.type MultiPoint) { return { type: geometry.type, coordinates: geometry.coordinates.map(c proj4(fromCrs, toCrs, c)) }; } if (geometry.type Polygon) { return { type: Polygon, coordinates: geometry.coordinates.map(ring ring.map(c proj4(fromCrs, toCrs, c))) }; } return geometry; }5.3 绘图体验调优的三个细节第一个细节地图交互冲突。绘图模式下需要禁用地图的拖拽平移否则画线时地图会跟着动导致坐标错乱。我在初始化地图时加了一个监听在绘图模式下动态切换map.on(draw.modechange, (e) { if (e.mode draw_polygon || e.mode draw_line_string || e.mode draw_point) { map.dragPan.disable(); } else { map.dragPan.enable(); } });第二个细节样式覆盖。插件默认的蓝色笔画在天地图这类深色底图上不够明显可以通过styles选项自定义比如把正在绘制的线条改成亮橙色const draw new MapboxDraw({ styles: [ { id: gl-draw-line, type: line, filter: [all, [, $type, LineString], [!, mode, static]], layout: { line-cap: round, line-join: round }, paint: { line-color: #ff6600, line-width: 3 } } ] });第三个细节移动端手指绘制时插件默认的touchEnabled可能影响缩放。建议在初始化参数里显式设置touchEnabled: true并配合map.touchZoomRotate.disable()在绘制时禁用双指手势。6. 常见问题排查速查表把一个多月的实战问题整理成了一张表遇到类似现象可以直接对照现象可能原因解决方案地图一片空白无瓦片请求token 未设置或无效检查mapboxgl.accessToken瓦片请求404坐标系网格不匹配按服务端 gridset 调整 z/x/y 换算图能出来但南北颠倒TMS/XYZ 的 Y 轴方向不一致source 加scheme: tms或 y 坐标取反瓦片模糊、字迹发虚真实瓦片尺寸和 tileSize 不一致确认是 256 还是 5124326瓦片加载后错位直接按3857网格请求了使用 transformRequest 换坐标绘制控件不显示缺少 CSS 引入引入mapbox-gl-draw.css绘制时地图跟着滑动拖拽平移未禁用draw.modechange 中 disable dragPan跨域报错切片服务无 CORS 头服务端加 CORS 或走代理放大后瓦片加载缓慢tiles 源缺少 minzoom/maxzoom显式设置缩放范围4490数据落库后偏差大前端未做坐标系转换proj4 定义 EPSG:4490 转换还有一个容易忽略的点Mapbox GL v2 对 HTTP 明文请求有限制如果你的页面是 HTTPS切片服务却是 HTTP浏览器会默认拦截混合内容导致瓦片加载失败。部署时尽量保持协议一致或者用代理转发。7. 写在最后这套方案在我项目里实际跑了一个多月累计加载了几十个图层最深的体会是坐标系问题永远不要指望前端“硬扛”能服务端解决的就在服务端解决前端只做展示和交互。尤其涉及 4326/4490 这类经纬度直投数据时统一在发布端转成 3857 切片能省掉后面 80% 的排查时间。如果确实只能在 Web 端直接消费 4326/4490 切片那transformRequest这招可以应急但一定要搞清楚服务端 gridset 的行列号定义而且接受它的精度上限。绘图控件的坐标导出则要记住一条铁律Mapbox 永远给你 WGS84业务需要什么坐标系就自己转。最后再分享一个小技巧调试瓦片换算时别直接盯着浏览器看地图打开 Network 面板手动构造几个瓦片 URL看看不同行列号返回的图片范围是否符合预期。把这一步验证通过坐标系的问题基本就解决了一大半。本文还有配套的精品资源点击获取