搞GIS地图前端的人十有八九都栽过这么一回拿高德JSAPI2.0当底图想把自己用GeoServer发布的WMS图层叠上去结果要么整个图层白茫茫一片要么瓦片错位得跟拼图似的。网上搜AMap.TileLayer.WMS相关的文章大部分翻来覆去就是官方demo那几句话参数说明恨不得让你自己猜。我把这套流程从GeoServer服务端到高德前端完整走了一遍把坐标系换算、请求拼接、常见盲区都捋清楚了。这篇文章适合做WebGIS、需要在高德底图上叠加业务图层的同学也适合刚接触GeoServer、对WMS请求一头雾水的新手。我这边实际碰到的业务场景是库里有一批shp格式的地质专题数据用GeoServer发布成WMS服务需要叠加到高德JSAPI2.0的底图上还要支持缩放、点击查询属性。听起来不复杂实际走下来才发现从数据坐标到瓦片编号、从服务配置到前端缓存每一步都可能让人怀疑人生。下面按我踩坑的顺序来写尽量做到你能直接照着做。1. 先搞明白高德底图、WMS服务和瓦片坐标系之间的三角关系在动手改代码之前建议先花十分钟把三个概念之间的差异搞清楚。很多人图层加载不出来就是没弄明白高德底图的切片方式、WMS服务的请求方式和坐标参考系这三者之间的关系。高德JSAPI2.0的底图是一张庞大的“瓦片金字塔”地图被切成256×256像素的小图片按缩放级别和行列号组织。它的投影基础是Web墨卡托也就是业内常说的EPSG:3857。不过高德在真实坐标上做了加密处理对外定位使用的是GCJ-02坐标系这就导致同一经纬度在高德底图上的像素位置和标准WGS84地图并不完全一致。但对于叠加业务图层来说真正关键的是瓦片网格的对齐方式也就是地图容器在请求透明瓦片时传给你的x、y、z编号够不够准确。WMS全称Web Map Service是一种动态地图服务。它不像普通瓦片那样预先切成N张小图而是根据客户端传来的范围bbox、尺寸width/height、图层名layers、坐标系srs等参数由服务器实时渲染出一张图片返回。GeoServer就是最常见的开源GIS服务器之一基于Java开发跨平台支持WMS、WMTS、WFS等一系列标准地理服务。用WMS的好处是灵活数据更新后不需要重新切瓦片坏处是每次请求都要实时计算尤其在大图层、高并发场景下压力很大。AMap.TileLayer.WMS这个类本质上是高德官方提供的一个“翻译层”。它的作用就是让高德地图在平移、缩放时把当前视口拆成若干瓦片坐标再把这些坐标交给getTileUrl函数由开发者拼成标准的WMS GetMap请求最后把返回的图片贴到高德底图对应的位置上。这里就是问题的高发区。高德传给getTileUrl的x、y、z并不能直接当作标准Web墨卡托瓦片编号去用。如果直接拿这三个数乘以256当作像素坐标去算bbox大概率会错位。同时GeoServer返回的图片必须和请求的bbox严格对应哪怕差一个像素拼出来的图都会出现接缝错位。这就是为什么“明明服务是好的叠上去却全乱套”。打个比方高德地图是一个只说某种方言的房东GeoServer是一个只会说标准普通话的租客你夹在中间当翻译。翻译错了房子就租不出去。下面这条链路里每一步都值得确认瓦片坐标换算、WMS服务配置、坐标系统一、请求参数拼接。2. 动手前先配好GeoServer服务端坐标系决定成败说句实在话很多前端报错根子其实在GeoServer环境。要么坐标没选对要么图层预览能看、单独请求却返回不了图片。我建议先把GeoServer侧的服务彻底调通再回到前端写代码不然两边同时都有问题排查起来非常折磨人。如果还没装GeoServer先去官网下最新稳定版。它是Java程序需要机器上有一个可用的Java运行环境安装包解压后直接双击启动脚本就行默认端口是8080。装好之后先创建一个工作区Workspace再上传shp数据发布图层。发布时能看到自动识别出来的坐标系信息这就是第一个要关注的重点。2.1 发布时坐标系的两种选择首先确认手上shp数据的原始坐标系。查看方法很多最简单的用QGIS打开图层属性或者直接看GeoServer发布向导里的“Coordinate Reference Systems”一栏GeoServer会自动读取数据自带的.prj文件。最常见的两种原始坐标系是EPSG:4326WGS84经纬度和EPSG:4490CGCS2000还有少数数据是EPSG:3857Web墨卡托。这里有个特别容易误解的点GeoServer发布图层时会区分“数据自带坐标系”和“发布后的坐标系”。默认情况下它会保持数据的原始坐标系不变但WMS请求时可以动态投影到任意坐标系。也就是说即使数据是4326别人用srsEPSG:3857发起请求时GeoServer也会现场投影后再渲染输出。那为什么还要纠结坐标系因为动态投影是有代价的。每次瓦片请求GeoServer都要把整个数据范围做一次投影变换图层数据量大时CPU会瞬间拉满前端表现就是转圈、白屏。所以我强烈建议如果这份数据确定要长期在高德这类Web墨卡托底图上用发布前先在GIS软件里转成EPSG:3857再上传。转换工具我用过QGIS的“导出-另存为”和GDAL命令行后者更适合批量处理一条指令就能搞定ogr2ogr -t_srs EPSG:3857 output.shp input.shp注意转换完成后最好把新的.prj文件打开看一眼确认里面写的是3857再上传。有时候默认输出的坐标系字段写法不太直观但GeoServer发布时能看到最终识别结果发布前检查一下就好。坐标系适用场景叠加高德底图时的注意点EPSG:4326原始经纬度数据、WGS84坐标动态投影到3857可用但大数据量性能压力大EPSG:4490国内CGCS2000经纬度数据同上建议提前转3857EPSG:3857Web墨卡托互联网地图通用与高德瓦片网格基本一致推荐使用2.2 用GetCapabilities和浏览器快速验证WMS服务GeoServer发布完图层之后先去浏览器里敲一下GetCapabilities请求这个请求会把服务器上所有可用的WMS图层信息、坐标系列表、支持的操作一次性列出来。地址通常长这样http://localhost:8080/geoserver/workspace/wms?serviceWMSversion1.1.0requestGetCapabilities如果这步都打不开先检查GeoServer进程和端口别急着怀疑前端。打开XML之后重点看两个信息一是图层的完整名称通常格式是“工作区名:图层名”比如“geo:geo_layer”别把工作区和图层名搞混二是该图层支持的坐标系看BoundingBox标签里列出来的坐标系代码。再进一步直接发一个GetMap请求在浏览器里看能不能出来一张图。最简请求长这样http://localhost:8080/geoserver/workspace/wms?serviceWMSversion1.1.0requestGetMaplayersworkspace:layernamebbox116.0,39.0,117.0,40.0width256height256srsEPSG:4326formatimage/png浏览器能直接显示图片说明服务端链路没问题。如果显示空白或报错多半就是图层名、bbox范围或srs写错了。这个过程只用几分钟能在后面排查问题时省下几个小时。3. 高德JSAPI2.0侧的具体实现把AMap.TileLayer.WMS用明白服务端调通后回到高德侧。这是整篇文章的核心中的核心也是踩坑最多的地方。3.1 官方参数只能说参考真正的逻辑在getTileUrl里高德JSAPI2.0的AMap.TileLayer.WMS官方文档给出的参数不多。常规写法是这样var wmsLayer new AMap.TileLayer.WMS({ tileSize: 256, crs: EPSG:3857, layers: workspace:layername, getTileUrl: function(x, y, z) { // 返回WMS请求地址 } });tileSize代表瓦片尺寸固定256crs看起来是坐标系参数layers是图层名。但实测下来真正决定图层显示结果的是getTileUrl里return的URL其他参数更多是内部占位和兜底不会自动帮你拼好请求。crs字段尤其别指望它做坐标转换你需要自己在getTileUrl里把坐标系和bbox算准确再拼进去。很多人在这里会遇到第一个坎getTileUrl里拿到的x、y、z到底代表什么高德地图容器在缩放级别为z时把整个Web墨卡托世界地图按2^z的规格切成行列瓦片x是列号y是行号原点在左上角。这一点和标准XYZ瓦片规则很像但因为高德地图坐标加密过直接拿经纬度反算出来的瓦片行列号和高德内部实际请求的行列号之间会有一个偏移。这个偏移量跟地图中心点和缩放级别都有关系不是固定值。3.2 高德瓦片坐标转3857包围盒的完整代码想真正把高德瓦片坐标转换成WMS服务需要的bbox核心思路是把瓦片坐标x、y、z转换为Web墨卡托投影坐标范围。哪怕高德本身做了坐标加密在大多数业务图层的精度要求下直接用标准Web墨卡托坐标去请求对接效果是可接受的。如果要把加密误差也完全消除需要把高德的瓦片编号先转换到WGS84网格再做GCJ-02纠偏反算过程比较复杂一般只有高精度轨迹叠加才会用这里先不展开。先给一个经过验证的转换函数// 根据Web墨卡托球体半径计算3857坐标范围 var originShift 2 * Math.PI * 6378137 / 2.0; // 20037508.342789244 function tileToMercator(x, y, z) { var resolution originShift * 2 / (256 * Math.pow(2, z)); var minX x * 256 * resolution - originShift; var maxX (x 1) * 256 * resolution - originShift; var maxY originShift - y * 256 * resolution; var minY originShift - (y 1) * 256 * resolution; return { minX: minX, minY: minY, maxX: maxX, maxY: maxY }; }然后拼WMS请求var wmsLayer new AMap.TileLayer.WMS({ tileSize: 256, getTileUrl: function(x, y, z) { var b tileToMercator(x, y, z); var bbox [b.minX, b.minY, b.maxX, b.maxY].join(,); return [ http://localhost:8080/geoserver/workspace/wms, ?serviceWMSversion1.1.0requestGetMap, layersworkspace:layername, styles, formatimage/png, transparentTRUE, srsEPSG:3857, bbox bbox, width256height256 ].join(); } }); wmsLayer.setMap(map);几个细节千万注意注意width和height必须和tileSize保持一致都是256否则瓦片比例会变形这是新手最高频的错误之一。注意transparentTRUE一定不能丢否则返回的图片会把底图盖成白板。srs要和bbox坐标系保持一致这里统一用EPSG:3857。version建议用1.1.0某些服务对接1.3.0时坐标轴顺序处理不太一样容易出一些莫名其妙的问题。我试过照搬某些帖子的写法把bbox按EPSG:4326的经纬度来拼配合高德底图当时也能显示但只要地图拖到其他区域就错位。原因就是4326经纬度坐标和Web墨卡托瓦片网格不是线性对应关系只有在小范围内偏差不明显。所以统一用3857才是稳妥做法。3.3 如果官方类不稳定用自定义TileLayer兜底AMap.TileLayer.WMS的本质是AMap.TileLayer的子类如果遇到奇怪问题完全可以绕开这个类直接自定义TileLayer实现同样的效果代码反而更透明var wmsTileLayer new AMap.TileLayer({ tileSize: 256, getTileUrl: function(x, y, z) { var b tileToMercator(x, y, z); return http://localhost:8080/geoserver/workspace/wms?serviceWMSversion1.1.0requestGetMaplayersworkspace:layernameformatimage/pngtransparentTRUEsrsEPSG:3857bbox [b.minX, b.minY, b.maxX, b.maxY].join(,) width256height256; } }); map.add(wmsTileLayer);这个方式我在实际项目里用得更多因为不受官方类内部实现影响逻辑完全掌握在自己手里。后续排查问题也建议先在这个透明实现上做验证确认没问题后再考虑用ANode官方类。4. 高频问题排查清单每一条都是我实际蹚过的这一段放在最后建议先把前面的代码跑通再回头看这些坑。每一条都是实际遇过的顺便给出排查思路。4.1 图层完全不显示先从最简单的确认Network面板里有没有发出GeoServer的WMS请求。有看请求返回值。没有说明getTileUrl没被调用或者返回了空串检查地图是否真的添加了图层、缩放级别是否被过滤。如果有请求但图片是空白先排查两个点一是图层名是不是带工作区前缀的完整名称比如geo:geo_layer少了工作区前缀GeoServer大概率返回400二是bbox范围是否在图层数据范围内比如数据范围在北京却请求了广州的地图范围当然什么也不出。GeoServer对很多错误不会直接报错到浏览器而是返回一张透明或白色的图所以不要觉得“有响应就等于正常”。我建议在浏览器里把请求URL复制出来单独开一个标签页访问这样能直接看到GeoServer返回的具体错误XML或状态码。大部分时候都是参数拼写问题一眼就能看出。4.2 图层错位、偏移、瓦片接缝混乱这是叠加WMS最头疼的问题。表现是图层能显示但位置不对或者图层的某个局部对不上瓦片与瓦片之间有明显割裂感。原因基本就三类第一坐标系不匹配。前端用srsEPSG:3857请求但GeoServer在发布时投影定义是错的或者数据本身空间参考信息缺失导致GeoServer没按预期投影。第二自己写的换算公式不对。很多人在算瓦片转bbox时把originShift算成了20037508.34而不是2倍结果整个坐标范围缩小一半。第三高德瓦片编号与内部切片规则不一致这多发生在特殊离线地图版本上。判断方法也简单用地图上一个明显的地物点比如河流拐弯处的坐标和GeoServer返回的同一点坐标做比对。错位幅度如果随缩放级别变化优先怀疑换算公式如果不管什么级别都偏一个固定距离优先怀疑坐标系和加密偏移问题。4.3 放大地图后瓦片空白或不更新这个坑很多人会遇到。地图在初始级别显示正常放大一级以后新瓦片不加载页面上留出一大片空白。我遇到过两种原因。一种是缩放级别被过滤。如果你在getTileUrl里写了if (z 5 || z 18) return 而GeoServer图层在某个级别渲染超时或数据范围外空白就会很显眼。把过滤条件放宽先看看更高层级到底有没有请求再决定要不要限制。另一种是浏览器端缓存导致。GeoServer默认会对WMS请求做一定程度的缓存返回的图片带Cache-Control头。瓦片在连续缩放时浏览器可能直接拿缓存的旧图看起来就是“不刷新”。临时解决办法是给请求参数加时间戳后缀tDate.now()但这个方案会破坏瓦片缓存生产环境不推荐。更合适的做法是在GeoServer侧开启GWC缓存让瓦片按金字塔规则缓存前端加载才会稳定。4.4 大图层加载慢、拖拽卡顿WMS是实时渲染服务图层数据量一旦上来卡顿几乎是必然。我之前接过一个省级地质图层的需求shp文件一百多MB直接WMS叠加地图缩放一次要等好几秒。后来做了两个优化一是在GeoServer发布时使用SLD样式降低渲染精度减少符号级别的计算量二是开启GWC缓存并设置合理的瓦片过期时间。前端配合AMap的缩放结束事件只在缩放结束后重新请求当前视口附近的瓦片操作流畅度提升明显。对于超大图层还可以考虑把shp导成PostGIS在数据库层面做空间索引让GeoServer每次取数只检索当前bbox里的数据而不是全表扫描。这一步对数据量大的生产环境几乎是必做的尤其当图层涉及多表关联或动态过滤时。4.5 点击瓦片获取图层信息怎么做叠加WMS之后很多需求会要求点击图层上的某个区域弹出属性信息。记住瓦片图片上是拿不到属性数据的需要调用WMS服务的GetFeatureInfo接口。思路是这样的在地图click事件里把鼠标点的经纬度换算成当前视口内的像素坐标再调用GetFeatureInfo。GeoServer的GetFeatureInfo请求参数和GetMap基本一样再加一个query_layers、x、y、info_format和feature_count参数。返回格式一般选application/json前端拿到GeoJSON就能自己画弹窗、做展示。map.on(click, function(ev) { var lnglat ev.lnglat; // 反算点击点在当前视口内的像素坐标 var pixel map.lngLatToContainer(lnglat, map.getZoom()); // 构造GetFeatureInfo请求 var url http://localhost:8080/geoserver/workspace/wms?serviceWMSversion1.1.0requestGetFeatureInfo layersworkspace:layernamequery_layersworkspace:layername x Math.round(pixel.getX()) y Math.round(pixel.getY()) info_formatapplication/json srsEPSG:3857bbox getCurrentViewportBBox(map) width256height256; fetch(url).then(res res.json()).then(data {}); });注意这里的x、y是相对于请求图片的像素坐标不是屏幕坐标很多人在这步搞混导致查出来的属性永远是旁边那个点的。如果前端用fetch请求时遇到跨域问题需要给GeoServer所在容器配置跨域响应头或者在网关层加Access-Control-Allow-Origin。5. 最后分享几个经验写到这里核心链路其实已经完整了。如果要总结踩坑心得那就是一句话高德JSAPI2.0叠加GeoServer WMS图层真正难的不是API调用而是把坐标系和瓦片规则这两件事想透。坐标系不统一前端代码再怎么改都是治标不治本瓦片坐标换算不准确加载出来的图永远差着一条接缝。我个人的习惯是接到这类需求后先别急着写代码先去GeoServer里把图层范围、坐标参考、服务端点都确认一遍然后拿固定bbox的请求在浏览器里直接验证图片是否正确最后才回到高德侧写TileLayer。能在服务端解决的问题不要在浏览器里浪费一小时。另外尽量减少对官方AMap.TileLayer.WMS封装的依赖。它只是一个很薄的封装实际干活的是你提供的getTileUrl。遇到问题要能拆开来看手动拼URL、手动验证往往比在封装层里找bug快得多。用自定义AMap.TileLayer实现同样的WMS叠加也是一个相当稳妥的备选方案。最后再分享一个工作流上的小技巧把瓦片坐标换算函数单独抽成公共模块加一份单元测试。项目里不同页面、不同业务图层都复用它以后如果要对接其他底图也只需要替换坐标系那一小部分。这样再遇到AMap.TileLayer.WMS相关的需求就不会被坐标系问题折腾到深夜了。
