简介围绕Java生成MVT切片与Mapbox前端调用的实战资源包面向Web地图开发和地理信息系统技术人员。资料以13个文件的压缩包形式提供主要包含7个JS脚本、3个HTML示例页面、2个CSS样式文件及1个备份文件。其中JS库覆盖Mapbox GL地图渲染、turf空间分析、绘图交互等能力HTML页面则展示了数据源与图层配置的完整写法配合CSS可快速搭建可交互的矢量瓦片地图应用。包体仅2.1MB轻量易用便于直接嵌入项目或对照学习。目前已有297人学习下载适合希望掌握MVT矢量切片生成原理、GeoJSON转换流程以及Mapbox GL JS调用方式的开发者。通过学习这份资源读者可以获得前后端衔接的完整示例理解Java后端处理地理数据、输出MVT切片以及前端按需加载渲染的实现思路并基于随包代码快速修改出自己的地图应用。1. 用 Java 生成 MVT 切片先解决地图渲染卡、样式不自由的痛点后端只吐一个全量 GeoJSON前端要去渲染全国 POI 图层数据量从几十 MB 涨到几百 MB 后浏览器开始卡到转圈。这个场景我处理过几次最后都落到同一个方案上用 java 生成 mvt 切片把海量矢量数据变成前端可以按需加载的小瓦片。MVTMapbox Vector Tile矢量瓦片按 z/x/y 网格把空间数据拆成一个个 .pbf前端只加载当前视野和缩放级别对应的那批文件样式由前端自己控制改颜色、隐藏图层都不用重新切图。这套做法适合自建地图服务的 Java 工程师、做规划领域图层管理的团队以及任何要在浏览器里高并发预览海量矢量数据的项目。2. MVT 切片涉及的三块基本功3857 投影、瓦片行列号与 pbf 内部结构MVT 切片表面上是“把几何切成小块”实际上绕不开三个底层约定Web Mercator 投影、z/x/y 行列号、pbf 里的 layer/feature 编码。这三块决定你写出来的切片器是“切得对”还是“切出来能飞线、错位、乱码”。2.1 Web Mercator 投影换算为什么切片前必须转 EPSG:3857绝大多数源数据是 WGS84 经纬度EPSG:4326而主流渲染端 MapLibre、Mapbox、Cesium 都以 Web MercatorEPSG:3857作为默认世界坐标。所以切 MVT 的通用做法是先统一到 3857。注意一点不是最后输出前“转一下坐标”就完事而是整个切片器的工作坐标系都要变成 3857尤其是瓦片范围裁剪否则第 5 章讲的错位问题一定会出现。Web Mercator 是把经纬度按墨卡托投影映射到一个正方形世界坐标里横坐标就是经度对应的弧长纵坐标是纬度的墨卡托函数单位是米。一个最简单的转换方法public static Point lonLatToWebMercator(double lon, double lat) { double x lon * (Math.PI / 180.0) * 6378137.0; double y Math.log(Math.tan(Math.PI / 4.0 lat * Math.PI / 360.0)) * 6378137.0; return new Point(x, y); }这里 6378137 是 WGS84 椭球的长半轴也是 Web Mercator 约定的球体半径。lat 接近 ±90 度时 tan 会趋向无穷所以读取数据后最好先把纬度夹在 ±85.0511 度以内这是 Web Mercator 的有效纬度边界超出部分没有实际地图意义。为什么强调在 3857 下做裁剪JTS 的 intersection 不关心坐标系的语义它只做数值计算。如果几何已经转成 3857 的米制坐标而瓦片边界还拿经纬度算两者的数值范围差了十万八千里intersection 结果就会是空集或者一条完全错误的线。我的习惯是在入口处统一完成一次 reproject后面所有逻辑都默认“当前几何已经是 3857”不要再混入任何经纬度坐标。2.2 瓦片行列号与裁剪范围一个要素到底该写进哪些 z/x/y给定缩放级别 z整个世界被分成 2^z 行、2^z 列的网格。把经纬度换算成瓦片行列号的公式是public static int[] lonLatToTile(double lon, double lat, int zoom) { double n Math.pow(2, zoom); int xTile (int) Math.floor((lon 180.0) / 360.0 * n); double latRad Math.toRadians(lat); double yTile (int) Math.floor( (1 - Math.log(Math.tan(latRad) 1 / Math.cos(latRad)) / Math.PI) / 2.0 * n); return new int[]{xTile, yTile}; }这个 y 公式看起来绕本质是把纬度先投影到 3857 世界坐标再按世界 y 轴从北到南切开。真正做切片时很少对每个要素单独算瓦片号更常见的做法是先拿到整个图层的包围盒算出它覆盖到哪些瓦片范围再逐瓦片循环public static int[] tileRange(Envelope bounds3857, int zoom) { double n Math.pow(2, zoom); double world 2 * Math.PI * 6378137.0; int minX (int) Math.floor((bounds3857.getMinX() / world 0.5) * n); int maxX (int) Math.floor((bounds3857.getMaxX() / world 0.5) * n); int maxY (int) Math.floor((0.5 - bounds3857.getMinY() / world) * n); int minY (int) Math.floor((0.5 - bounds3857.getMaxY() / world) * n); return new int[]{minX, maxX, minY, maxY}; }注意瓦片 y 坐标是自上而下增长的而 3857 的 y 轴是向上为正所以取 y 范围时要翻转边界。这段代码返回 {minX, maxX, minY, maxY}正好可以套三层循环for x、for y、for zoom。有了瓦片号还需要知道每个瓦片在 3857 坐标系里的矩形边界这个边界就是裁剪依据。3857 下整个世界是一个正方形瓦片边界在米制坐标里是均匀切分的public static Envelope tileEnvelope3857(int z, int x, int y) { double n Math.pow(2, z); double world 2 * Math.PI * 6378137.0; double minX (x / n - 0.5) * world; double maxX ((x 1) / n - 0.5) * world; double minY (0.5 - (y 1) / n) * world; double maxY (0.5 - y / n) * world; return new Envelope(minX, maxX, minY, maxY); }这个方法的输出就是 3.3 里裁剪要用到的 tileBox。实践中可以预先缓存同一 zoom 的 n 和 world避免每个瓦片都重复算一遍。2.3 .pbf 文件内部Layer、Feature、Geometry 三个层级和 extentMVT 的产物是 Protocol Buffers 编码的二进制文件名通常是 y.pbf 或 y.mvt扩展名不影响内容。一个 .pbf 内部可以包含多个图层每个图层下是一批要素要素里再装几何和属性。理解它的层级结构调试乱码、错位、要素丢失时才不会瞎猜。结构关键字段作用Tile 顶层layers 列表一个 pbf 可装多个图层前端按 source-layer 取用Layername, version, extentname 对应前端 source-layerextent 是坐标网格范围Featureid, tags, type, geometrytags 是属性索引type 是几何类型Geometrycommand 流用 zigzag 编码的相对整数坐标不是经纬度Layer 里那个 extent 是理解 MVT 的关键。extent 默认是 4096意思是瓦片内的坐标范围是 0 到 4096几何坐标全部相对瓦片左上角归一化到这个网格里。前端渲染时再把 0 到 4096 映射到屏幕像素。所以切片代码在编码前必须做一次坐标整数化这也是 3.4 要单独说的原因。3. 用 Java 跑通最小切片生成GeoTools 读数据、JTS 裁剪、编码写盘有了第 2 章的理论现在进入可复现的部分。这一章给出一个最小切片器骨架读者可以照抄后替换自己的数据源和图层字段。3.1 选型对比自研切片器 vs. planetiler 现成引擎Java 生态里生成 MVT 有两条主流路线直接用 planetiler 这类现成引擎或者用 GeoTools JTS 自己在服务里切。planetiler 本身是 Java 技术栈用配置文件声明数据源和图层就能产出 mbtiles性能很好适合标准格式的全量切图。但它对要素的加工方式比较固定想接业务库做权限过滤、字段定制时扩展成本不低。方案上手成本控制力适合场景planetiler 现成引擎低配置化中标准 shp/geojson/gpkg 全量切图GeoTools JTS 自研中需自己处理投影和裁剪高嵌入 Java 服务、动态过滤、增量切片标题既然问“使用 java 生成 mvt 切片的方法”说明大概率是要在自己的 Java 工程里产出瓦片。下面以自研为主因为参数怎么调、坑在哪这些经验无论用哪种方案都通用。如果只是要一次性把全国数据切好我建议你先用 planetiler 试一遍省时间。3.2 搭建依赖pom.xml 里要引入哪些模块自研方案的核心依赖是 GeoTools 的 gt-main、gt-shapefile、gt-referencing、gt-mvt以及 JTS 的 jts-core。版本不写死用你们项目正在维护的稳定版本即可properties geotools.version你的 GeoTools 版本/geotools.version jts.version你的 JTS 版本/jts.version /properties dependencies dependency groupIdorg.geotools/groupId artifactIdgt-main/artifactId version${geotools.version}/version /dependency dependency groupIdorg.geotools/groupId artifactIdgt-shapefile/artifactId version${geotools.version}/version /dependency dependency groupIdorg.geotools/groupId artifactIdgt-referencing/artifactId version${geotools.version}/version /dependency dependency groupIdorg.geotools/groupId artifactIdgt-mvt/artifactId version${geotools.version}/version /dependency dependency groupIdorg.locationtech.jts/groupId artifactIdjts-core/artifactId version${jts.version}/version /dependency /dependenciesGeoTools 的部分模块需要额外配置发布仓库Maven Central 里不一定全按你所用版本的官方文档补一下仓库配置。如果你用的 GeoTools 版本里没有 gt-mvt 模块就找对应版本的 mvt 扩展包或者退一步用 mapbox 的 vector-tile 底层库自己组装整体方案不变。3.3 Tiler 主流程从源文件到 z/x/y 目录下面是一个最小切片器主流程我故意保留了方法桩方便读者替换自己的实现。核心逻辑是先读取并重投影再计算瓦片范围最后对每个瓦片裁剪、编码、写盘public class MvtTiler { private final int minZoom 4; private final int maxZoom 14; private final int extent 4096; private final int buffer 64; public void generate(Path sourceFile, Path outRoot) throws Exception { // 1. 读取源要素并全部转到 EPSG:3857 ListSimpleFeature features loadAndReproject(sourceFile, EPSG:4326, EPSG:3857); if (features.isEmpty()) return; // 2. 计算整体范围用于限制瓦片遍历区间 Envelope whole featuresBounds(features); for (int z minZoom; z maxZoom; z) { int[] range tileRange3857(whole, z); for (int x range[0]; x range[1]; x) { for (int y range[2]; y range[3]; y) { Envelope tileBox tileEnvelope3857(z, x, y); // 把 buffer 加进裁剪范围但写入 pbf 时仍按原 tileBox 计算相对坐标 Envelope clipBox new Envelope(tileBox); clipBox.expandBy(bufferMeters(z)); ListSimpleFeature clipped clipToTile(features, clipBox); if (clipped.isEmpty()) continue; byte[] pbf encodeTile(clipped, tileBox); writePbf(outRoot, z, x, y, pbf); } } } } }逻辑说明loadAndReproject 负责把源数据统一成 3857tileRange3857 来自第 2.2 章clipToTile 用 JTS intersection 做裁剪encodeTile 是编码环节。tileBox 是当前瓦片的真实边界clipBox 是加了 buffer 的边界赋值几何相对坐标时一定要用 tileBox否则前端渲染会错位。bufferMeters 是把 buffer 从像素/瓦片单位换算成 3857 的米换算公式在后面参数章节讲。这个骨架看起来不长但已经覆盖“读取、计算、裁剪、编码、写盘”五步。真正接入工程时loadAndReproject 和 encodeTile 是最容易翻车的两个方法下面展开。3.4 编码前的坐标整数化extent、buffer 与要素偏移loadAndReproject 的核心是 GeoTools 的坐标变换。常见做法是先用 CRS.decode 拿 MathTransform再逐要素用 JTS.transform 转换几何private static ListSimpleFeature loadAndReproject(Path source, String srcCRS, String dstCRS) throws Exception { FileDataStore store FileDataStoreFinder.getDataStore(source.toFile()); SimpleFeatureCollection collection store.getFeatureSource().getFeatures(); MathTransform transform CRS.findMathTransform(CRS.decode(srcCRS), CRS.decode(dstCRS), true); ListSimpleFeature result new ArrayList(); try (SimpleFeatureIterator it collection.features()) { while (it.hasNext()) { SimpleFeature f it.next(); Geometry g (Geometry) f.getDefaultGeometry(); if (g null) continue; Geometry reprojected JTS.transform(g, transform); result.add(SimpleFeatureBuilder.build(f.getFeatureType(), new Object[]{reprojected, f.getAttribute(name)}, f.getID())); } } return result; }代码里 SimpleFeatureBuilder.build 的字段顺序要和你源 FeatureType 一致稳妥点可以直接复制属性列表而不是手写 name 属性。CRS.findMathTransform 第三个参数 true 表示允许长度不精确变换能省不少计算量。encodeTile 内部最容易出问题的步骤是“把 3857 米制坐标转成瓦片本地整数坐标”。因为 MVT 的 pbf 只接受整数坐标必须落到 [0, extent] 区间private static Geometry toTileLocal(Geometry geometry, Envelope tileBox, int extent) { Geometry local geometry.copy(); local.apply(new CoordinateSequenceFilter() { Override public void filter(CoordinateSequence seq, int i) { double px (seq.getX(i) - tileBox.getMinX()) / tileBox.getWidth() * extent; double py (seq.getY(i) - tileBox.getMinY()) / tileBox.getHeight() * extent; seq.setOrdinate(i, 0, Math.round(px)); seq.setOrdinate(i, 1, Math.round(py)); } Override public boolean isGeometryChanged() { return true; } }); return local; }这里用 Math.round 而不是强转 int强转是截断会让几何整体偏移最多一个坐标单位在 4096 extent 下就是约 0.25 个显示像素多级联动后会出现明显的锯齿和错位。实际 encodeTile 里把这层 local 几何连同属性字段一起交给 gt-mvt 的 MVTEncoder传清楚 tileBox 和 extent 就行。不同版本 GeoTools 的 MVTEncoder 方法签名略有差别以你依赖版本里的 javadoc 为准但输入无非就是三个东西要素集合、瓦片边界、extent。4. 切片参数怎么调extent、buffer、简化阈值与层级策略代码跑通只是起点参数没调好切出来的瓦片要么体积爆炸要么渲染边缘全是裂缝。这一章讲四个每次切图都要过的参数。4.1 extent 与 buffer 怎么搭配4096 不是万金油extent 决定瓦片内坐标网格的粒度常见值是 1024、2048、4096。值越大几何精度越高但 pbf 里的整数值越大体积也越大值越小文件越小但复杂多边形会明显失真文字标注容易扭曲。extent视觉精度文件体积适用场景1024粗线面容易折角最小极大数据量、低端设备降级2048中等中常规图层4096高大默认推荐道路/行政面用这个我一般默认 extent4096只有做海量 POI 或性能压测时才降到 2048。配合 extentbuffer 是渲染阶段最容易出问题的参数。MVT 的每个瓦片只保存自己范围附近的要素但前端渲染时因为描边、阴影、跨瓦片边界会把相邻瓦片边缘的几何也画出来。如果生成端没在瓦片四周额外保留一段几何相邻瓦片交界处就会出现白线或断线。buffer 的经验值是“一个渲染像素对应的地面范围再放大一点”。256 像素渲染瓦片下buffer 取 64 像素是常见配置换算到 4096 extent 时clipBox 大约向外扩 10% 的瓦片宽度。注意 buffer 只影响裁剪和编码坐标相对原点的计算仍然按原 tileBox 做这一点在 3.3 已经提醒过。4.2 几何简化用多大容差按 zoom 换算地面精度源数据精度高不代表每个 zoom 都要原样输出。zoom 4 的一根道路线如果保留 zoom 14 的所有顶点pbf 体积会大几十倍前端加载还慢。常见做法是用 JTS 的 DouglasPeuckerSimplifier按当前 zoom 的像素分辨率设置容差public static Geometry simplifyForZoom(Geometry g, int z, double pixelTolerance) { double worldWidth 2 * Math.PI * 6378137.0; double metersPerPixel worldWidth / (Math.pow(2, z) * 256.0); double tolerance metersPerPixel * pixelTolerance; return DouglasPeuckerSimplifier.simplify(g, tolerance); }metersPerPixel 是“当前 zoom 下每个渲染像素代表多少米”。pixelTolerance 取 0.5意味着视觉上最多容忍半像素的形变人眼基本看不出来。道路、水系这类线条取 0.5 到 1.0 都没问题多边形边界建议保守一点取 0.3POI 点位千万不要简化点位本身不占多少体积简化反而会把精确位置改歪。简化太狠的典型翻车是两条并行道路在中低 zoom 被压成一条或者交叉路口的连接关系断裂。所以我的习惯是简化只作用于输出前那一层原始要素始终保留方便某个层级不满意时重新切而不是从头读一遍数据。4.3 分层与缩放范围用规则表控制每个 layer 的输出级别业务数据往往是一张表road 表里有高速、国道、乡道poi 表里有几十万条点。把它们全部切到所有 zoom 是浪费。一个可维护的办法是配置一张层级规则表规定每类要素在哪些级别输出、按什么属性过滤。MapString, int[] layerZoom new HashMap(); layerZoom.put(road, new int[]{8, 14}); layerZoom.put(poi, new int[]{14, 16}); layerZoom.put(boundary, new int[]{4, 12}); MapString, PredicateSimpleFeature layerFilter new HashMap(); layerFilter.put(road, f - { String cls (String) f.getAttribute(class); return motorway.equals(cls) || trunk.equals(cls); });在切片循环里每个 zoom 先查 layerZoom不满足直接 continue每个要素再过 layerFilter被过滤掉就不进编码器。这套规则表的好处是前端想调整显示策略时后端只改配置不用改切片代码。低 zoom 只出主要道路和边界高 zoom 才出 POIpbf 数量和单文件体积都能收到一个合理范围。5. MVT 切片避坑指南5 个常见故障的现象、原因和解决这一章是我在这类项目里攒下的血泪经验。每一条都按“现象、原因、解决”写读者可以直接对照排查。5.1 瓦片边缘出现细线裂缝缓冲区设小或简化过头现象前端地图缩放时相邻瓦片交界处道路出现白线或断裂缩放动画里尤其明显。 原因生成端 buffer 设得太小跨界要素在相邻瓦片里没有被保留足够多的外部几何或者简化容差设得太大把跨界处用来衔接的顶点抽掉了。 解决先把生成端 buffer 提到不低于 64 像素对应范围再检查简化容差是否小于 buffer 的一半。我曾经把简化 tolerance 调到 1.5 像素后全线出现裂缝降回 0.5 像素立刻正常。这个坑和参数强相关用第 4 章的换算公式重算一遍就好。5.2 跨 180° 经线的飞线几何没做清洗和边界拆分现象一根线横穿整张地图把东经 179 度和西经 -179 度连成一条“横跨地球”的线视觉上像飞线。 原因源数据里跨越 antimeridian180° 经线的要素在 4326 坐标下被表示成一段从 179 跳到 -179 的线段转到 3857 后这段线就穿过了整张世界地图。另外JTS 处理自相交几何时也会给出错误结果。 解决读取后先对 geometry 做一次geometry.buffer(0)清理自相交再把经度坐标统一规整到 [-180, 180]。如果业务范围真的会跨 180 度需要单独把几何按 180 度线拆分分成两条要素再进切片主流程。多数国内业务不涉及但做全球数据时一定要加这一步。5.3 shapefile 中文属性乱码读取时字符集没对上现象pbf 用工具读出来属性名和属性值是乱码或者直接变成问号前端 tooltip 无法显示中文。 原因shapefile 的 dbf 属性文件常用 GBK 编码而 GeoTools 的默认字符集不一定是 GBK读进 Java String 之前就已经乱掉了。这种乱码是不可逆的编码成 pbf 之后更难看出来。 解决读取 shp 时显式指定字符集。ShapefileDataStore store new ShapefileDataStore(shpFile.toURI().toURL()); store.setCharset(Charset.forName(GBK)); SimpleFeatureSource source store.getFeatureSource();注意如果 dbf 本身已经是乱码比如用文本编辑器打开就是乱码那不是切片代码的问题是源数据有问题。先用 QGIS 另存为 UTF-8 的 shapefile 或 GeoPackage再做切片。5.4 小瓦片文件数爆炸批量写与 mbtiles 聚合现象切全国数据到 z14散文件达到上百万个磁盘 inode 被吃光后续部署到服务器也慢。 原因每个瓦片单独创建文件、单独 flushIO 开销大目录式散文件天然不适合海量小文件切图时并行线程开太多反而因为磁盘竞争变慢。 解决如果产物需要单文件分发用 mbtiles 方案把 pbf 写进 SQLite一个文件管所有层级如果必须散文件至少用 BufferedOutputStream 攒一批再落盘。并行度控制在 4 到 8SSD 上超过 8 线程切图快不了多少反而带来大量 IO 等待。5.5 点位偏移几百米坐标系在裁剪时混用现象点位、线、面整体偏移几百米到几公里zoom 越大偏移越明显。 原因几何已经转成 3857但瓦片范围或裁剪 Envelope 还在用 4326 的数值计算JTS 不感知坐标系intersection 在数值上不报错输出结果却是完全错误的。 解决切片器里只保留一套坐标系。入口统一转 3857瓦片边界一律用 2.2 章的 tileEnvelope3857 方法生成不要随手 new 一个 Envelope(west, east, south, north) 去裁剪。我排查这类问题时会先打印 geometry 的坐标范围和 tileBox 的范围看数值量级是否匹配一次就能定位。6. 切片输出后的质量校验先读回 pbf再上渲染端验收切片切完不能直接交差至少要做两步验证第一步是结构校验确认 pbf 能解析、图层名和 extent 对第二步是渲染验证让前端真正加载一两张瓦片看效果。读回 pbf 做结构校验不需要起前端服务用 mapbox 的 vector-tile 类就能快速解析Tile tile Tile.parseFrom(Files.readAllBytes(Paths.get(12/1234/567.pbf))); for (Tile.Layer layer : tile.getLayersList()) { System.out.printf(layer%s extent%d features%d%n, layer.getName(), layer.getExtent(), layer.getFeaturesCount()); }检查三个点layer 名是否和前端 style 里的 source-layer 对得上extent 是否等于你配置的 4096feature 数量是否和源数据在瓦片范围内的预期数量接近。这三项过了基本说明管线通了。渲染验证我一般用 MapLibre GL 本地起个静态服务加载切片目录并叠加道路样式。常看到有人搜“cesium加载mvt格式”真要用 Cesium 加载 MVT 还得转 3D Tiles日常验证直接用 MapLibre 更快它原生支持 vector source。我现在每次调完切片参数都会先选一个包含跨 180° 线、中文属性和复杂多边形的县级范围切到 z12 跑一遍三项校验通过再全量切。这个习惯帮我把重切成本压得很低希望帮到你。本文还有配套的精品资源点击获取