尧图网站建设 
简介面向需要搭建矢量地图服务的 Java 与前端开发者这份资源围绕 Java 生成 MVT 切片、Mapbox GL JS 前端调用提供一套可直接运行的示例。整体来看内容覆盖 GeoJSON 转 MVT、切片服务接口设计、前端矢量源与图层配置等关键环节也包含常见的地图交互与样式调整思路适合正在实现自定义 Web 地图或希望理解 MVT 数据流转的初中级开发者参考。压缩包共 13 个文件大小 2.1MB含 7 个 JavaScript 库或脚本、3 个 HTML 示例页面、2 个 CSS 样式文件、1 个备份文件其中 JS 涵盖地图渲染、绘图交互、地理计算等能力HTML 演示地图初始化与矢量图层渲染CSS 控制控件样式bak 可作修改底稿。这套资源已有 296 人学习下载解压后可直接打开示例查看效果省去依赖库整理时间能帮助读者把 Java 后端生成的 MVT 服务快速对接到前端地图中重点流程和调用关系一目了然。 去年做一个路况数据可视化项目时后端一次返回几万个轨迹点和车辆点前端用 canvas 渲染直接卡死缩放地图更是想都不用想。后来我把数据切成 MVTMapbox Vector Tile矢量切片前端加载从三秒多降到几百毫秒拖动和缩放都跟手了。这个项目让我把 Java 生成 MVT 的这条路完整走了一遍从概念补课、方案选型到实际编码和踩坑都积累了不少经验。这篇就围绕“使用 java 生成 mvt 切片的方法”展开把整个流程讲透特别是那些常规文档里不会写的细节。这篇文章适合两类人一类是 Java 后端项目里要接地图数据但之前没接触过 GIS 相关概念另一类是已经用 GeoServer 或 PostGIS 出过切片但想在服务内部拿到更细颗粒度的控制权自己用代码生成 MVT 的开发者。无论你是哪种看完都应该能独立跑出一个可用的 MVT 切片服务。1. MVT切片是什么矢量瓦片的核心逻辑与常见误区1.1 MVT与图片切片的本质区别先说清楚 MVT 到底是什么。MVT 全称 Mapbox Vector Tile是一种基于 Protocol Buffers 的矢量瓦片格式把地理数据按照瓦片网格切分成小块每块里包含的是几何数据和属性数据而不是渲染好的图片像素。图片切片大家可能比较熟就是把一张大地图预先渲染成很多 PNG 或 JPEG 小图前端按需加载。这种方案的问题是样式固定死了想换颜色、换线宽就得重新渲染数据更新也要重新出图而且高清屏下图片会发虚。MVT 则是把“数据”发给前端由前端渲染引擎比如 MapLibre GL JS实时绘制。好处很明显样式随便换前端改个 style 就行文件体积小因为存的是坐标点和属性缩放时矢量图形不会糊。我用一个生活化类比图片切片是厨房做好一桌菜端上来你只能吃现成的MVT 是给你一份食材和菜谱你想怎么炒就怎么炒。这个区别直接决定了选型方向。1.2 坐标系和层级必须先搞懂的两个概念要生成 MVT绕不开两个基本概念坐标系和层级。这里不展开讲完整的地理投影理论只说实用的部分。我们平时用的经纬度是 WGS84 坐标系EPSG:4326而 MVT 瓦片是基于 Web 墨卡托投影EPSG:3857组织的。Web 墨卡托把地球近似成一个正方形范围是[-20037508.3427892, 20037508.3427892]这样每一级的瓦片网格都是整齐的 2 的幂次方分割。层级zoom level从 0 开始第 0 级是整个世界一张瓦片第 1 级切成 4 张第 2 级切成 16 张以此类推。第 z 级的瓦片总数是2^z * 2^z。每一张瓦片又被划分成extent x extent的网格extent 通常是 4096 或 512。注意这个 extent 不同于瓦片像素尺寸它是 MVT 内部的坐标参考网格。实际编码时GeoJSON 里的经纬度要先投影成 Web 墨卡托的平面坐标再换算到当前层级下某张瓦片内部的局部坐标。这个换算写起来不难但很容易出错后面踩坑部分我会细说。2. Java生态里生成MVT的路线选择从GeoServer到轻量编码库2.1 先问自己需要离线预处理还是实时生成Java 生态生成 MVT 有好几条路选哪条取决于你的业务场景。我把它分成两类离线预处理和实时生成。离线预处理适合数据基本不变、更新频率低的情况。比如行政区划边界、路网数据、建筑轮廓这种数据一个月更新一次都算频繁了。这类场景可以直接用 GeoServer GeoWebCache通过配置自动把 PostGIS 里的数据切成 MVT存成文件或直接由 GeoServer 发布成 WMTS 服务。实时生成适合数据频繁变化、需要查询什么就切什么的场景。比如实时车辆位置、订单热点分布、动态轨迹数据每次都走 GeoServer 反而绕。这时候更适合在业务服务里直接调用 Java 编码库生成 MVT 瓦片甚至可以把查询条件和切片逻辑结合做到按需切片。我的项目里轨迹数据是秒级更新的用户又经常按时间范围筛选显然不适合离线预处理所以我走了实时生成路线。但如果你只是要给静态数据做个可视化页面强烈建议先考虑 GeoServer别上来就自己写省下的时间够你干别的了。2.2 各方案的对比和选型参考方案基本定位适用场景上手成本优点缺点GeoServer GeoWebCache重量级 GIS 服务器静态数据、标准 OGC 服务中高功能全、社区大、支持多数据源部署重、二次开发麻烦wdttec/vector-tile轻量级 MVT 编码库Java 服务内动态切片低依赖少、API 简洁、基于 JTS需要自己处理数据查询和缓存noelbundick/vector-tileMVT 编码库较早学习原理、简单场景低代码少、容易读源码功能相对简单维护不如前者活跃自研基于 Protobuf 方案深度定制极特殊的 MVT 需求高完全可控工作量大、划不来对比之后我选了 wdttec/vector-tile。原因有三一是它基于 JTSJava Topology Suite而我的数据源就来自 PostGISJTS 是天然衔接的数据模型二是打包后依赖小可以嵌在 Spring Boot 服务里不需要单独维护 GIS 服务器三是它的 API 设计简单核心类就那几个读源码也快。如果只是学习 MVT 格式本身noelbundick 的项目更小适合拿来读。2.3 一个容易被忽略的前提数据从哪来生成 MVT 之前数据源得能提供空间查询能力。最理想的是 PostGIS直接把空间字段查出来用ST_AsGeoJSON转成 GeoJSON或者直接拿 JTS 的 Geometry 对象。如果你的数据不在数据库里而是普通的 CSV、JSON 文件那得先用 JTS 的WKTReader或GeoJSONReader把几何对象加载进来再做切片。这个过程看着简单但要注意如果你的数据量很大一次性加载到内存里是不现实的需要按瓦片范围过滤后再加载。所以数据源的规划最好在切片方案之前就想清楚。3. 用vector-tile库跑通第一个Demo依赖配置、核心API与坐标换算3.1 Maven依赖与初始化先用 Maven 引入依赖dependency groupIdcom.wdttec/groupId artifactIdvector-tile/artifactId version1.3.4/version /dependency这个库的核心类是TileEncoder它的作用是把 JTS 的Geometry对象编码成 MVT 的字节数组。使用流程很简单创建TileEncoder往里面添加要素最后调用encode()拿到byte[]。import com.wdttec.vector.tile.TileEncoder; import com.wdttec.vector.tile.TileEncoder.Feature; import org.locationtech.jts.geom.Geometry; TileEncoder encoder new TileEncoder(layerName, 4096); encoder.addFeature(new Feature(geometry, attributes)); byte[] mvtBytes encoder.encode();这里的layerName是图层名称前端加载 MVT 时会用到4096是 extent前端请求瓦片时需要保持一致。3.2 坐标换算从经纬度到瓦片局部坐标最关键的步骤是坐标换算直接把经纬度塞给编码器是不行的。需要先把经纬度从 EPSG:4326 投影到 EPSG:3857再换算成当前瓦片内部的相对坐标。我封装了一个工具方法public static double[] lngLatToMvt(double lng, double lat, int zoom, int tileX, int tileY, int extent) { double n Math.pow(2, zoom); double x (lng 180.0) / 360.0 * n; double latRad Math.toRadians(lat); double y (1 - Math.log(Math.tan(latRad) 1 / Math.cos(latRad)) / Math.PI) / 2.0 * n; double tileXDouble Math.floor(x); double tileYDouble Math.floor(y); double localX (x - tileXDouble) * extent; double localY (y - tileYDouble) * extent; return new double[]{localX, localY, tileXDouble, tileYDouble}; }这个方法里做了三件事第一步计算经纬度在 Web 墨卡托投影下的全局瓦片坐标x, y第二步确定当前瓦片的编号tileX, tileY第三步把全局坐标减去瓦片原点得到瓦片内部的局部坐标乘以 extent 换算到 MVT 的坐标空间。注意这里计算出的tileX、tileY要和前端请求的瓦片编号一致否则坐标会偏到别的瓦片上去。实际项目里前端传的是{z}/{x}/{y}后端就用这套参数来切。3.3 几何对象的处理与编码坐标换算好之后要把每个坐标点替换回 Geometry。这里有个简单的做法用 JTS 的GeometryTransformer重写所有坐标。GeometryTransformer transformer new GeometryTransformer() { Override protected CoordinateSequence transformCoordinates( CoordinateSequence coords, Geometry parent) { ListCoordinate newCoords new ArrayList(); for (int i 0; i coords.size(); i) { double lng coords.getX(i); double lat coords.getY(i); double[] mvtCoord lngLatToMvt(lng, lat, zoom, tileX, tileY, extent); newCoords.add(new Coordinate(mvtCoord[0], mvtCoord[1])); } return new CoordinateArraySequence(newCoords.toArray(new Coordinate[0])); } }; Geometry tileGeometry transformer.transform(sourceGeometry);这一步做完之后tileGeometry就是瓦片局部坐标下的几何对象可以直接传给TileEncoder。要注意空几何的问题。如果一条线段刚好落在瓦片边界之外裁剪后的 Geometry 可能是空的直接编码会报错。最好加个判断if (tileGeometry null || tileGeometry.isEmpty()) { return; // 跳过这个要素 }3.4 完整流程串联把上面的东西串起来一个完整的 Controller 方法GetMapping(/tile/{z}/{x}/{y}.mvt) public ResponseEntitybyte[] getTile( PathVariable int z, PathVariable int x, PathVariable int y) throws Exception { // 1. 查询该瓦片范围内的数据 BoundingBox bbox tileToBoundingBox(z, x, y); ListGeometry geometries queryFromPostGIS(bbox); // 2. 坐标换算 编码 TileEncoder encoder new TileEncoder(myLayer, 4096); for (Geometry g : geometries) { Geometry tileGeom transformGeometry(g, z, x, y); if (tileGeom null || tileGeom.isEmpty()) continue; encoder.addFeature(new Feature(tileGeom, null)); } byte[] mvt encoder.encode(); // 3. 返回注意 Content-Type 和 Content-Encoding HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.parseMediaType(application/vnd.mapbox-vector-tile)); return new ResponseEntity(mvt, headers, HttpStatus.OK); }这个 Demo 能跑通之后MVT 的基本流程就算掌握了。但真正用到生产环境你大概率会遇到下面这些坑。4. 实测踩坑记录坐标反向、低层级抽稀与MVT闭环验证4.1 坑一MVT的坐标轴方向和 GeoJSON 相反第一个坑是坐标反向。MVT 规范的坐标系是 y 轴向上而屏幕坐标系和 GeoJSON 常见的坐标顺序是[经度, 纬度]看起来都是 x 在前、y 在后但很多人在坐标换算时会忽略 y 轴方向。我最初写lngLatToMvt时localY直接用y - tileYDouble算没做反转。结果地图上的点上下颠倒河流变成了天上的河。后来查了规范才发现MVT 的本地坐标 y 轴是朝上的而 PNG 图片的 y 轴是朝下的两者正好相反。解决办法很简单在编码前把局部坐标的 y 轴翻转double localY extent - (y - tileYDouble) * extent; // 注意这里但这个翻转只在某些编码器里是必须的wdttec 的库内部是怎么处理的最好自己读一下源码确认。这个读源码确认的经验非常重要因为不同库实现有差异照着网上的教程写可能正好是反的。4.2 坑二extent 不匹配导致前端白图第二个坑是 extent 不匹配。前端 MapLibre GL JS 加载 MVT 时会在请求瓦片的 URL 里带2x或直接指定extent比如https://example.com/tile/{z}/{x}/{y}.mvt?extent4096。如果后端编码时用的 extent 是 4096而某个前端组件默认按 512 来解析渲染出来的图形就会错位或直接消失。我当时排查了很久才发现问题后端一直在 4096 下编码但调试用的某个前端库固定按 512 解析导致所有特征点都不在正确位置上。最后统一前端请求参数和后端编码参数并把 extent 固定为 4096 才解决。这里我建议把 extent 作为配置项统一管理并且在前端请求 URL 中明确带上extent4096后端也读取这个参数来决定编码用的 extent避免两端不一致。4.3 坑三低层级时坐标被抽稀掉LineString 变成了点第三个坑和坐标精度有关。MVT 编码时几何坐标最终会被转换成整数。在低层级比如 z2、z3时整个地球才 4 到 16 张瓦片一条很长的 LineString 在一个瓦片内可能只占几个像素宽度坐标经整数化之后多个顶点会落到同一个整数坐标上。这时候如果编码库做了顶点去重或简化原本的线就可能退化成几个点前端看起来就是 LineString 变成了一堆不连续的小点甚至直接消失。解决思路有两种。一种是在低层级时不做过度的简化算法保留全部顶点另一种是适当提高低层级的 extent比如低层级用 4096高层级也保持 4096。但要留意坐标的取值范围是[0, extent]超出这个范围的坐标会被裁剪掉所以不能无限加大 extent。我在项目里经过实测z2 级别用 4096 extent 基本够用z0 和 z1 这种极低层级可以单独用 8192或者干脆不输出 MVT直接展示一个聚合点的 GeoJSON。这种不同层级不同策略的思路在真实项目中很常见。4.4 MVT闭环验证不能只看文件大小要渲染出来看最后一个建议验证 MVT 正确性别只看编码不报错、文件大小合理就以为完事了。MVT 是二进制格式肉眼看不出来内容必须用前端渲染或专门的工具来验证。我的验证流程分三步先用tippecanoe-decode一个命令行工具解码生成的 MVT检查里面每一层的要素数量、几何类型、属性字段。这一步能发现大部分坐标偏移和几何丢失的问题。再用 MapLibre GL JS 加载验证重点看几何是否在正确位置、不同缩放级别下是否有要素丢失、图形有没有明显变形。最后做性能测试分别请求 z10、z14、z18 的瓦片记录响应时间和体积。我的实测数据是数据库里 760 万条记录的情况下单张瓦片平均查询耗时 100ms 左右编码耗时 80ms 左右响应体体积大多在 20KB 到 80KB 之间前端加载很流畅。如果你没有 tippecanoe-decode 这种工具也可以打开浏览器的开发者工具直接看请求返回的 MVT 文件大小以及渲染结果至少能发现哪些瓦片是空的哪些位置明显不对这类明显问题。5. 进阶优化缓存策略、属性过滤和跨层级一致性5.1 缓存策略不要每次都从数据库查实时生成 MVT 要做缓存否则数据库扛不住。常见的做法是 LRU 缓存key 为z/x/y加上数据版本号。我的项目里用 Caffeine 做了两级缓存热数据存内存最近 2000 张瓦片冷数据存本地磁盘文件名为z_x_y.mvt缓存失效时间控制在 5 分钟以内。这样既保证了轨迹数据的新鲜度又不会让数据库承受太大的查询压力。一个值得注意的细节瓦片缓存的 key 最好加上参数版本号。比如数据源更新时间、当前筛选条件否则用户切换条件后看到的还是旧数据排查起来特别迷惑。5.2 属性过滤按需保留落到瓦片里的属性MVT 里每个要素可以带属性。属性太多会显著增大瓦片体积前端解析也会变慢。所以编码前应该过滤属性只保留前端渲染需要的那几个字段。比如路况数据我只需要 roadId、speed、status、name 这四个字段但原始查询结果里还有长度、宽度、更新时间、行政区划码等一堆字段。我在查询 SQL 里就只 select 需要的字段而不是在 Java 里再做一遍过滤。数据库少传数据、Java 少处理对象、瓦片体积更小整体性能明显提升。5.3 跨层级一致性避免缩放时要素跳变如果你做过地图可视化一定遇到过缩放时要素突然消失或者突然冒出来的情况。这在 MVT 里很常见主要是相邻层级之间瓦片切分边界不一致导致的。解决思路是在生成每张瓦片时把周边的要素也做一定程度的缓冲或包含处理确保要素跨越瓦片边界时两边都有完整的几何形状。具体到实现就是在查询数据库时把 bbox 按一定比例向外扩展比如扩展 10%。这里要注意扩展 bbox 后多余的要素会在编码时被裁掉所以不会影响瓦片规范性只是增加了查询和编码的计算量。实测下来10% 的扩展在性能和视觉效果之间是比较平衡的点。我在实际项目里,这几个优化做完之后MVT 服务才真正达到了可上线的状态。缓存让 qps 从几十提升到几百属性过滤让平均瓦片体积降了一半以上跨层级一致性让前端渲染效果好了一个档次。每个项目的数据场景不一样但把坐标换算、extent 一致性、缓存策略这几个点拿捏住了Java 生成 MVT 这条路基本不会出大问题。如果你也在这条路上踩过坑或者有什么更好的思路欢迎一起交流。特别是 wdttec 这个库虽然好用但文档不多很多细节都是试出来的多一个人验证就少一个坑。本文还有配套的精品资源点击获取 Java生成MVT矢量切片：从坐标换算到性能优化的完整实践
简介面向需要搭建矢量地图服务的 Java 与前端开发者这份资源围绕 Java 生成 MVT 切片、Mapbox GL JS 前端调用提供一套可直接运行的示例。整体来看内容覆盖 GeoJSON 转 MVT、切片服务接口设计、前端矢量源与图层配置等关键环节也包含常见的地图交互与样式调整思路适合正在实现自定义 Web 地图或希望理解 MVT 数据流转的初中级开发者参考。压缩包共 13 个文件大小 2.1MB含 7 个 JavaScript 库或脚本、3 个 HTML 示例页面、2 个 CSS 样式文件、1 个备份文件其中 JS 涵盖地图渲染、绘图交互、地理计算等能力HTML 演示地图初始化与矢量图层渲染CSS 控制控件样式bak 可作修改底稿。这套资源已有 296 人学习下载解压后可直接打开示例查看效果省去依赖库整理时间能帮助读者把 Java 后端生成的 MVT 服务快速对接到前端地图中重点流程和调用关系一目了然。 去年做一个路况数据可视化项目时后端一次返回几万个轨迹点和车辆点前端用 canvas 渲染直接卡死缩放地图更是想都不用想。后来我把数据切成 MVTMapbox Vector Tile矢量切片前端加载从三秒多降到几百毫秒拖动和缩放都跟手了。这个项目让我把 Java 生成 MVT 的这条路完整走了一遍从概念补课、方案选型到实际编码和踩坑都积累了不少经验。这篇就围绕“使用 java 生成 mvt 切片的方法”展开把整个流程讲透特别是那些常规文档里不会写的细节。这篇文章适合两类人一类是 Java 后端项目里要接地图数据但之前没接触过 GIS 相关概念另一类是已经用 GeoServer 或 PostGIS 出过切片但想在服务内部拿到更细颗粒度的控制权自己用代码生成 MVT 的开发者。无论你是哪种看完都应该能独立跑出一个可用的 MVT 切片服务。1. MVT切片是什么矢量瓦片的核心逻辑与常见误区1.1 MVT与图片切片的本质区别先说清楚 MVT 到底是什么。MVT 全称 Mapbox Vector Tile是一种基于 Protocol Buffers 的矢量瓦片格式把地理数据按照瓦片网格切分成小块每块里包含的是几何数据和属性数据而不是渲染好的图片像素。图片切片大家可能比较熟就是把一张大地图预先渲染成很多 PNG 或 JPEG 小图前端按需加载。这种方案的问题是样式固定死了想换颜色、换线宽就得重新渲染数据更新也要重新出图而且高清屏下图片会发虚。MVT 则是把“数据”发给前端由前端渲染引擎比如 MapLibre GL JS实时绘制。好处很明显样式随便换前端改个 style 就行文件体积小因为存的是坐标点和属性缩放时矢量图形不会糊。我用一个生活化类比图片切片是厨房做好一桌菜端上来你只能吃现成的MVT 是给你一份食材和菜谱你想怎么炒就怎么炒。这个区别直接决定了选型方向。1.2 坐标系和层级必须先搞懂的两个概念要生成 MVT绕不开两个基本概念坐标系和层级。这里不展开讲完整的地理投影理论只说实用的部分。我们平时用的经纬度是 WGS84 坐标系EPSG:4326而 MVT 瓦片是基于 Web 墨卡托投影EPSG:3857组织的。Web 墨卡托把地球近似成一个正方形范围是[-20037508.3427892, 20037508.3427892]这样每一级的瓦片网格都是整齐的 2 的幂次方分割。层级zoom level从 0 开始第 0 级是整个世界一张瓦片第 1 级切成 4 张第 2 级切成 16 张以此类推。第 z 级的瓦片总数是2^z * 2^z。每一张瓦片又被划分成extent x extent的网格extent 通常是 4096 或 512。注意这个 extent 不同于瓦片像素尺寸它是 MVT 内部的坐标参考网格。实际编码时GeoJSON 里的经纬度要先投影成 Web 墨卡托的平面坐标再换算到当前层级下某张瓦片内部的局部坐标。这个换算写起来不难但很容易出错后面踩坑部分我会细说。2. Java生态里生成MVT的路线选择从GeoServer到轻量编码库2.1 先问自己需要离线预处理还是实时生成Java 生态生成 MVT 有好几条路选哪条取决于你的业务场景。我把它分成两类离线预处理和实时生成。离线预处理适合数据基本不变、更新频率低的情况。比如行政区划边界、路网数据、建筑轮廓这种数据一个月更新一次都算频繁了。这类场景可以直接用 GeoServer GeoWebCache通过配置自动把 PostGIS 里的数据切成 MVT存成文件或直接由 GeoServer 发布成 WMTS 服务。实时生成适合数据频繁变化、需要查询什么就切什么的场景。比如实时车辆位置、订单热点分布、动态轨迹数据每次都走 GeoServer 反而绕。这时候更适合在业务服务里直接调用 Java 编码库生成 MVT 瓦片甚至可以把查询条件和切片逻辑结合做到按需切片。我的项目里轨迹数据是秒级更新的用户又经常按时间范围筛选显然不适合离线预处理所以我走了实时生成路线。但如果你只是要给静态数据做个可视化页面强烈建议先考虑 GeoServer别上来就自己写省下的时间够你干别的了。2.2 各方案的对比和选型参考方案基本定位适用场景上手成本优点缺点GeoServer GeoWebCache重量级 GIS 服务器静态数据、标准 OGC 服务中高功能全、社区大、支持多数据源部署重、二次开发麻烦wdttec/vector-tile轻量级 MVT 编码库Java 服务内动态切片低依赖少、API 简洁、基于 JTS需要自己处理数据查询和缓存noelbundick/vector-tileMVT 编码库较早学习原理、简单场景低代码少、容易读源码功能相对简单维护不如前者活跃自研基于 Protobuf 方案深度定制极特殊的 MVT 需求高完全可控工作量大、划不来对比之后我选了 wdttec/vector-tile。原因有三一是它基于 JTSJava Topology Suite而我的数据源就来自 PostGISJTS 是天然衔接的数据模型二是打包后依赖小可以嵌在 Spring Boot 服务里不需要单独维护 GIS 服务器三是它的 API 设计简单核心类就那几个读源码也快。如果只是学习 MVT 格式本身noelbundick 的项目更小适合拿来读。2.3 一个容易被忽略的前提数据从哪来生成 MVT 之前数据源得能提供空间查询能力。最理想的是 PostGIS直接把空间字段查出来用ST_AsGeoJSON转成 GeoJSON或者直接拿 JTS 的 Geometry 对象。如果你的数据不在数据库里而是普通的 CSV、JSON 文件那得先用 JTS 的WKTReader或GeoJSONReader把几何对象加载进来再做切片。这个过程看着简单但要注意如果你的数据量很大一次性加载到内存里是不现实的需要按瓦片范围过滤后再加载。所以数据源的规划最好在切片方案之前就想清楚。3. 用vector-tile库跑通第一个Demo依赖配置、核心API与坐标换算3.1 Maven依赖与初始化先用 Maven 引入依赖dependency groupIdcom.wdttec/groupId artifactIdvector-tile/artifactId version1.3.4/version /dependency这个库的核心类是TileEncoder它的作用是把 JTS 的Geometry对象编码成 MVT 的字节数组。使用流程很简单创建TileEncoder往里面添加要素最后调用encode()拿到byte[]。import com.wdttec.vector.tile.TileEncoder; import com.wdttec.vector.tile.TileEncoder.Feature; import org.locationtech.jts.geom.Geometry; TileEncoder encoder new TileEncoder(layerName, 4096); encoder.addFeature(new Feature(geometry, attributes)); byte[] mvtBytes encoder.encode();这里的layerName是图层名称前端加载 MVT 时会用到4096是 extent前端请求瓦片时需要保持一致。3.2 坐标换算从经纬度到瓦片局部坐标最关键的步骤是坐标换算直接把经纬度塞给编码器是不行的。需要先把经纬度从 EPSG:4326 投影到 EPSG:3857再换算成当前瓦片内部的相对坐标。我封装了一个工具方法public static double[] lngLatToMvt(double lng, double lat, int zoom, int tileX, int tileY, int extent) { double n Math.pow(2, zoom); double x (lng 180.0) / 360.0 * n; double latRad Math.toRadians(lat); double y (1 - Math.log(Math.tan(latRad) 1 / Math.cos(latRad)) / Math.PI) / 2.0 * n; double tileXDouble Math.floor(x); double tileYDouble Math.floor(y); double localX (x - tileXDouble) * extent; double localY (y - tileYDouble) * extent; return new double[]{localX, localY, tileXDouble, tileYDouble}; }这个方法里做了三件事第一步计算经纬度在 Web 墨卡托投影下的全局瓦片坐标x, y第二步确定当前瓦片的编号tileX, tileY第三步把全局坐标减去瓦片原点得到瓦片内部的局部坐标乘以 extent 换算到 MVT 的坐标空间。注意这里计算出的tileX、tileY要和前端请求的瓦片编号一致否则坐标会偏到别的瓦片上去。实际项目里前端传的是{z}/{x}/{y}后端就用这套参数来切。3.3 几何对象的处理与编码坐标换算好之后要把每个坐标点替换回 Geometry。这里有个简单的做法用 JTS 的GeometryTransformer重写所有坐标。GeometryTransformer transformer new GeometryTransformer() { Override protected CoordinateSequence transformCoordinates( CoordinateSequence coords, Geometry parent) { ListCoordinate newCoords new ArrayList(); for (int i 0; i coords.size(); i) { double lng coords.getX(i); double lat coords.getY(i); double[] mvtCoord lngLatToMvt(lng, lat, zoom, tileX, tileY, extent); newCoords.add(new Coordinate(mvtCoord[0], mvtCoord[1])); } return new CoordinateArraySequence(newCoords.toArray(new Coordinate[0])); } }; Geometry tileGeometry transformer.transform(sourceGeometry);这一步做完之后tileGeometry就是瓦片局部坐标下的几何对象可以直接传给TileEncoder。要注意空几何的问题。如果一条线段刚好落在瓦片边界之外裁剪后的 Geometry 可能是空的直接编码会报错。最好加个判断if (tileGeometry null || tileGeometry.isEmpty()) { return; // 跳过这个要素 }3.4 完整流程串联把上面的东西串起来一个完整的 Controller 方法GetMapping(/tile/{z}/{x}/{y}.mvt) public ResponseEntitybyte[] getTile( PathVariable int z, PathVariable int x, PathVariable int y) throws Exception { // 1. 查询该瓦片范围内的数据 BoundingBox bbox tileToBoundingBox(z, x, y); ListGeometry geometries queryFromPostGIS(bbox); // 2. 坐标换算 编码 TileEncoder encoder new TileEncoder(myLayer, 4096); for (Geometry g : geometries) { Geometry tileGeom transformGeometry(g, z, x, y); if (tileGeom null || tileGeom.isEmpty()) continue; encoder.addFeature(new Feature(tileGeom, null)); } byte[] mvt encoder.encode(); // 3. 返回注意 Content-Type 和 Content-Encoding HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.parseMediaType(application/vnd.mapbox-vector-tile)); return new ResponseEntity(mvt, headers, HttpStatus.OK); }这个 Demo 能跑通之后MVT 的基本流程就算掌握了。但真正用到生产环境你大概率会遇到下面这些坑。4. 实测踩坑记录坐标反向、低层级抽稀与MVT闭环验证4.1 坑一MVT的坐标轴方向和 GeoJSON 相反第一个坑是坐标反向。MVT 规范的坐标系是 y 轴向上而屏幕坐标系和 GeoJSON 常见的坐标顺序是[经度, 纬度]看起来都是 x 在前、y 在后但很多人在坐标换算时会忽略 y 轴方向。我最初写lngLatToMvt时localY直接用y - tileYDouble算没做反转。结果地图上的点上下颠倒河流变成了天上的河。后来查了规范才发现MVT 的本地坐标 y 轴是朝上的而 PNG 图片的 y 轴是朝下的两者正好相反。解决办法很简单在编码前把局部坐标的 y 轴翻转double localY extent - (y - tileYDouble) * extent; // 注意这里但这个翻转只在某些编码器里是必须的wdttec 的库内部是怎么处理的最好自己读一下源码确认。这个读源码确认的经验非常重要因为不同库实现有差异照着网上的教程写可能正好是反的。4.2 坑二extent 不匹配导致前端白图第二个坑是 extent 不匹配。前端 MapLibre GL JS 加载 MVT 时会在请求瓦片的 URL 里带2x或直接指定extent比如https://example.com/tile/{z}/{x}/{y}.mvt?extent4096。如果后端编码时用的 extent 是 4096而某个前端组件默认按 512 来解析渲染出来的图形就会错位或直接消失。我当时排查了很久才发现问题后端一直在 4096 下编码但调试用的某个前端库固定按 512 解析导致所有特征点都不在正确位置上。最后统一前端请求参数和后端编码参数并把 extent 固定为 4096 才解决。这里我建议把 extent 作为配置项统一管理并且在前端请求 URL 中明确带上extent4096后端也读取这个参数来决定编码用的 extent避免两端不一致。4.3 坑三低层级时坐标被抽稀掉LineString 变成了点第三个坑和坐标精度有关。MVT 编码时几何坐标最终会被转换成整数。在低层级比如 z2、z3时整个地球才 4 到 16 张瓦片一条很长的 LineString 在一个瓦片内可能只占几个像素宽度坐标经整数化之后多个顶点会落到同一个整数坐标上。这时候如果编码库做了顶点去重或简化原本的线就可能退化成几个点前端看起来就是 LineString 变成了一堆不连续的小点甚至直接消失。解决思路有两种。一种是在低层级时不做过度的简化算法保留全部顶点另一种是适当提高低层级的 extent比如低层级用 4096高层级也保持 4096。但要留意坐标的取值范围是[0, extent]超出这个范围的坐标会被裁剪掉所以不能无限加大 extent。我在项目里经过实测z2 级别用 4096 extent 基本够用z0 和 z1 这种极低层级可以单独用 8192或者干脆不输出 MVT直接展示一个聚合点的 GeoJSON。这种不同层级不同策略的思路在真实项目中很常见。4.4 MVT闭环验证不能只看文件大小要渲染出来看最后一个建议验证 MVT 正确性别只看编码不报错、文件大小合理就以为完事了。MVT 是二进制格式肉眼看不出来内容必须用前端渲染或专门的工具来验证。我的验证流程分三步先用tippecanoe-decode一个命令行工具解码生成的 MVT检查里面每一层的要素数量、几何类型、属性字段。这一步能发现大部分坐标偏移和几何丢失的问题。再用 MapLibre GL JS 加载验证重点看几何是否在正确位置、不同缩放级别下是否有要素丢失、图形有没有明显变形。最后做性能测试分别请求 z10、z14、z18 的瓦片记录响应时间和体积。我的实测数据是数据库里 760 万条记录的情况下单张瓦片平均查询耗时 100ms 左右编码耗时 80ms 左右响应体体积大多在 20KB 到 80KB 之间前端加载很流畅。如果你没有 tippecanoe-decode 这种工具也可以打开浏览器的开发者工具直接看请求返回的 MVT 文件大小以及渲染结果至少能发现哪些瓦片是空的哪些位置明显不对这类明显问题。5. 进阶优化缓存策略、属性过滤和跨层级一致性5.1 缓存策略不要每次都从数据库查实时生成 MVT 要做缓存否则数据库扛不住。常见的做法是 LRU 缓存key 为z/x/y加上数据版本号。我的项目里用 Caffeine 做了两级缓存热数据存内存最近 2000 张瓦片冷数据存本地磁盘文件名为z_x_y.mvt缓存失效时间控制在 5 分钟以内。这样既保证了轨迹数据的新鲜度又不会让数据库承受太大的查询压力。一个值得注意的细节瓦片缓存的 key 最好加上参数版本号。比如数据源更新时间、当前筛选条件否则用户切换条件后看到的还是旧数据排查起来特别迷惑。5.2 属性过滤按需保留落到瓦片里的属性MVT 里每个要素可以带属性。属性太多会显著增大瓦片体积前端解析也会变慢。所以编码前应该过滤属性只保留前端渲染需要的那几个字段。比如路况数据我只需要 roadId、speed、status、name 这四个字段但原始查询结果里还有长度、宽度、更新时间、行政区划码等一堆字段。我在查询 SQL 里就只 select 需要的字段而不是在 Java 里再做一遍过滤。数据库少传数据、Java 少处理对象、瓦片体积更小整体性能明显提升。5.3 跨层级一致性避免缩放时要素跳变如果你做过地图可视化一定遇到过缩放时要素突然消失或者突然冒出来的情况。这在 MVT 里很常见主要是相邻层级之间瓦片切分边界不一致导致的。解决思路是在生成每张瓦片时把周边的要素也做一定程度的缓冲或包含处理确保要素跨越瓦片边界时两边都有完整的几何形状。具体到实现就是在查询数据库时把 bbox 按一定比例向外扩展比如扩展 10%。这里要注意扩展 bbox 后多余的要素会在编码时被裁掉所以不会影响瓦片规范性只是增加了查询和编码的计算量。实测下来10% 的扩展在性能和视觉效果之间是比较平衡的点。我在实际项目里,这几个优化做完之后MVT 服务才真正达到了可上线的状态。缓存让 qps 从几十提升到几百属性过滤让平均瓦片体积降了一半以上跨层级一致性让前端渲染效果好了一个档次。每个项目的数据场景不一样但把坐标换算、extent 一致性、缓存策略这几个点拿捏住了Java 生成 MVT 这条路基本不会出大问题。如果你也在这条路上踩过坑或者有什么更好的思路欢迎一起交流。特别是 wdttec 这个库虽然好用但文档不多很多细节都是试出来的多一个人验证就少一个坑。本文还有配套的精品资源点击获取