简介天地图离线API完整包是一套专为开发者准备的本地化地图资源目标是让应用在无网络环境下依然能够调用天地图核心能力。它面向Web GIS开发、内网部署以及户外应急等场景省去实时联网获取瓦片的依赖同时保留地图展示、搜索、路径规划、轨迹移动等常见交互。压缩包共2000个文件大小仅6.02MB以1991张PNG瓦片图片为主体辅以7个JavaScript脚本、1个HTML入口和1个CSS样式表其中脚本分别承担地图加载、D3图层渲染、军标标绘、车辆轨迹跟踪等功能HTML与CSS负责页面框架及显示外观。已有2999人学习/下载实用性得到一定验证。拿到后可将其直接部署到自有服务器或本地目录快速搭建一套完整的离线地图服务环境并且能够实现轨迹记录、移动展示等高级操作适合应急响应、户外作业等弱网场景。使用时还需留意地图数据的版权合规并根据道路和城市变化定期更新瓦片以保持时效性。1. 项目背景与核心需求1.1 天地图API的常见痛点天地图是国家地理信息公共服务平台提供的在线API覆盖了地图显示、坐标拾取、空间查询、路线规划、轨迹回放等常用功能。实际做GIS项目时我最常被问到的问题不是“这些功能怎么调”而是“这套API能不能离线用”。原因其实很现实很多项目运行在政务内网、涉密环境或者偏远工区的专网里这些环境物理隔离或者只能访问个别白名单地址外网根本不通。你想在这样一套网络里做一张能看地图、能查坐标、能跑轨迹的系统直接用官网在线API是行不通的。另一个典型场景是稳定性。在线API再稳也扛不住带宽抖动和接口升级。早些年我负责过一个油气管道巡检系统就因为第三方地图服务接口调整导致一大片巡检轨迹无法回放甲方直接炸毛。所以很多做GIS的同行最后都走向了同一件事把天地图官网的API完整包拿下来部署到本地让所有操作不依赖外网。1.2 离线版要解决的是什么问题所谓“天地图离线API完整包”就是把官网Web API所依赖的JavaScript库、样式文件、图片资源、配置文件以及底图瓦片数据或者瓦片转发代理打包成本地资源让页面通过本地路径就能加载这些API同时所有地图操作都在本地完成。关键点在于“支持官网所有的操作”这不仅仅是看个静态地图还包括覆盖物绘制、坐标转换、逆地理编码、距离量算、缓冲区分析以及标题里特别提出的“轨迹移动”——也就是把一串带时间戳的坐标点在地图上动起来真实模拟车辆或人员的移动过程。做离线版不只是把在线地址改成相对路径那么简单。天地图的在线API内部会去请求官网的瓦片服务地址、token校验接口、服务端计算接口。如果你直接断网页面一加载就报错。所以完整的离线包必须把API运行依赖的底层服务请求也一并处理掉要么内置本地瓦片数据库要么搭建一个本地代理服务模拟官网的接口返回规范。这也是为什么网上传的很多“离线API精简包”一用就废因为它们只做了静态文件搬运没做接口层替换。1.3 完整包到底包含什么按我自己的拆解习惯一个真正能用的天地图离线API完整包应该包含四类内容第一类是API核心程序包括天地图的JavaScript库、CSS样式、字体和图标文件版本号要与官网对齐第二类是本地地图数据至少包含离线瓦片包层级覆盖项目区域可以从官网或其他合规渠道获取或者用工具从在线资源切片导出第三类是代理服务或者模拟接口用来处理pid、tk等密钥校验逻辑将原来需要远程请求的接口改为本地返回第四类是功能扩展示例包括坐标拾取、轨迹回放、比例尺控制等官网常见操作的Demo代码。只有这四类东西齐整才算得上“完整包”。另外要注意市面上有些离线包版本比较老对应的是旧版天地图API。旧版和新版在初始化方式、图层类型、回调函数签名上都有些差异。如果项目本身是用新版API开发的一定得确认离线包版本能对应上否则加载地图时黑屏、绑定事件不触发这些怪问题就会冒出来。2. 离线API包的架构拆解2.1 基本地图显示与图层加载天地图API初始化地图的核心方法是new T.Map(mapDiv)地图的默认底图由瓦片图层控制。在线模式下API会按照当前视图中心点计算瓦片编号然后去官网的t{0-7}.tianditu.gov.cn路径下拼接瓦片URL。离线模式下最省事的做法是改造瓦片URL的拼接逻辑让请求指向本地静态瓦片目录。我常用的办法是把瓦片按z/x/y.png的目录结构存放然后重写T.TileLayer的getTilesUrl方法。这样地图的缩放、拖拽、瓦片请求全部走本地不占外网流量。实际测试下来加载速度和内网带宽强相关千兆内网里瓦片基本秒出。还需要处理的是投影坐标系。天地图使用CGCS2000EPSG:4490坐标系且是经纬度直投显示。如果你拿到了离线瓦片但底图偏斜对不上坐标大概率是瓦片的生产器把坐标系搞错了。瓦片切图时务必检查元数据里的坐标系定义这是底图展示的根基。2.2 空间分析能力的本地化天地图官网API提供了不少空间分析功能像T.GeometryUtil里的距离计算、面积计算以及T.Overlay下的点线面绘制、缓冲区分析等。离线包要支持这些操作关键是不要依赖服务端计算。好消息是这些分析本质上都是纯数学运算可以直接在前端完成。以距离量算为例两地之间的球面距离可以通过Haversine公式实现精度在GPS轨迹场景下完全够用。我自己做离线包的时候会把T.GeometryUtil里的源码抽出来编译进本地JS文件。因为新版官网里不少工具类被压缩混淆了直接引用网上扒下来的非压缩源码反而和官方行为不一致。稳妥的做法是先用官网在线页面把对应功能跑一遍记录请求返回的JSON结构再用本地mock数据模拟返回。比如逆地理编码接口T.Geocoder在线模式请求的是api.tianditu.gov.cn/geocoder离线模式下就得自己做一份本地行政区划和兴趣点的索引数据按经纬度匹配最近的名称返回结构保持和官网一致上层业务代码才不用改。2.3 轨迹移动的实现机制轨迹移动是离线API里最复杂的部分因为它涉及到时间轴控制、坐标插值、地图视角跟随和动画渲染四件事。官网的T.Polyline本身只负责画静态线路离线包要实现的“轨迹移动”相当于自己开发一套动画逻辑。我的实现思路是先准备一条轨迹数据格式为[{lng:116.3,lat:39.9,time:1520000000}, ...]按时间戳排序。然后创建Marker对象通过requestAnimationFrame按固定帧率比如30fps读取当前帧对应的插值坐标。插值方式用线性插值就够了如果轨迹点间隔过大或要求平滑可以改用Catmull-Rom样条插值。核心代码其实就是计算时间进度把时间差映射到坐标点之间。在这过程中许多人容易忽略一个问题地图中心点的跟随。轨迹移动时Marker已经跑出了屏幕视野体验极差。正确做法是每次更新Marker位置后同步调用map.panTo(new T.LngLat(lng, lat), {duration: 50})做平滑移动。还要注意如果轨迹数据跨级缩放需要动态调整最小缩放级别否则marker移动速度太快视觉上会“瞬移”。离线环境里没有官网的轨迹回放控件所以这些全部要自己处理。好在纯前端实现没有什么代码量负担一个轨迹播放器类控制在三百行左右就能搞定。3. 实操部署与集成步骤3.1 部署前的环境准备先说部署环境。离线API包本质是静态网站资源所以部署方式很多可以直接放在Nginx里跑也可以打成jar包塞进SpringBoot项目的static目录甚至用Caddy、IIS都行。我自己更倾向用Nginx配置简单、跨域好处理、瓦片文件多的时候并发性能也够。部署前要把天地图官网的API版本核对好。打开https://api.tianditu.gov.cn/api页面查看当前版本号比如v4.0。然后下载对应的JS和CSS文件。如果项目里还用到卫星影像、地形晕渲等图层需要把对应样式的瓦片数据一起准备好。需要特别提醒的是瓦片数据版权归属天地图离线使用前最好确认使用范围避免合规风险。另外要确认浏览器环境。天地图API对IE11是支持的但轨迹动画依赖requestAnimationFrameIE下需要做降级处理。我的做法是写一个polyfill在浏览器不支持时用setInterval兜底帧率降到20fps功能不受影响。3.2 核心代码实现轨迹回放下面直接给一段我之前项目里抽出来的核心代码可以看成实现轨迹移动的最小闭环。// 初始化地图 var map new T.Map(mapDiv, { projection: EPSG:4326, center: new T.LngLat(116.39, 39.9), zoom: 10 }); // 使用本地瓦片 var tileLayer new T.TileLayer({ getTilesUrl: function(x, y, z) { return ./tiles/${z}/${x}/${y}.png; } }); map.addLayer(tileLayer); // 轨迹点数组带时间戳 var trackPoints [ { lng: 116.39, lat: 39.90, t: 1600000000 }, { lng: 116.41, lat: 39.92, t: 1600000010 }, { lng: 116.44, lat: 39.91, t: 1600000020 }, // ... ]; // 轨迹播放器 class TrackPlayer { constructor(map, points) { this.map map; this.points points; this.marker new T.Marker(new T.LngLat(points[0].lng, points[0].lat)); this.marker.addTo(map); this.index 0; this.startTime 0; this.running false; } start() { this.index 0; this.startTime Date.now(); this.running true; this.tick(); } tick() { if (!this.running) return; var elapsed (Date.now() - this.startTime) / 1000; // 将时间偏移转为轨迹索引示例按固定步长实际应根据t字段插值 var progress elapsed * 1000; // 假设每毫秒移动1次 this.index Math.min(Math.floor(progress / 200), this.points.length - 1); var p this.points[this.index]; var lnglat new T.LngLat(p.lng, p.lat); this.marker.setLngLat(lnglat); this.map.panTo(lnglat, { duration: 50 }); if (this.index this.points.length - 1) { requestAnimationFrame(() this.tick()); } else { this.running false; } } }上面代码简化了实际使用真正落地时还要根据轨迹点自带的时间戳计算速度而不是固定步长。如果两点间隔10秒但距离有1公里按固定步长动画会忽快忽慢。我通常先遍历所有点把累积距离算出来再结合时间戳算每帧的期望距离然后反推出当前坐标这种方案在公路轨迹和无人机航迹上都验证过。3.3 与ArcGIS/QGIS的联动很多用户拿到离线API后不只是做网页展示还希望把天地图底图接入本地的桌面GIS工具比如ArcGIS和QGIS。这块和离线API包本身关系不大但经常被一起问。在QGIS里加载天地图可以使用官方离线插件或者在浏览器里通过WMTS方式添加。如果是纯离线环境ArcGIS加载天地图影像通常是以ArcMap的WMTS图层或者ArcGIS Server的缓存图层方式接入。这里要区分清楚离线API包提供的是JavaScript前端接口ArcGIS/QGIS用的是标准地图服务协议两者不直接互通。如果你需要同时支持网页端和桌面端最好在本地发布一个符合OGC标准的瓦片服务例如用GeoServer把离线瓦片发布成WMTS网页端和ArcGIS都能用。我在实际项目里就遇到甲方要求网页端用轨迹回放桌面端用ArcGIS做叠加分析。我的解决办法是保留两套资源瓦片数据共用一套文件夹网页端走自定义图层ArcGIS本地发布一个缓存服务这样两头数据一致不用维护两份。4. 常见问题与排查技巧实录4.1 API Token的离线绕过问题天地图在线API在初始化时一般需要token参数。离线包最常遇到的坑就是页面控制台报login failed. check api token之类的错误或者接口返回“403”显示token无效。这是因为官网JS内部会向远程服务器发送token校验请求。离线环境下没有远程服务器校验逻辑自然走不通。处理方案有三种。第一种最简单的是把打开官网页面时获得的token直接写入本地配置并修改API源码中的校验函数让它在离线时不发起网络请求直接return true。第二种是搭建一个本地模拟服务响应/js/checkresult这类校验接口返回合法JSON。第三种是把官网API中的T.Utils.checkToken方法整体替换成空函数或者本地校验逻辑。这里需要提醒一下修改API源码前一定要保留原文件备份否则混入在线/离线混合环境时很难排查问题。我通常是写一个构建脚本用正则或者简单字符串替换在打包时自动完成替换确保每次重新打包结果一致。4.2 坐标系与比例尺范围问题天地图默认使用经纬度直投显示坐标显示格式通常是“116.39,39.9”这和WGS84坐标在数值上很接近但理论上是CGCS2000框架下的经纬度。做离线包时如果直接把在线网页里的坐标数据拿过来用误差通常在几米到几十米这种精度对普通人眼完全没影响。但如果要和测绘级数据叠加就需要注意坐标基准统一。比例尺范围是另一个高频问题。天地图官方的比例尺范围一般是3级到19级具体看你当前分辨率。离线瓦片如果只切到15级地图放大到16级就会出现空白。我建议在离线包里加一个缩放级别判断当用户放大到超过瓦片最大级别时弹出提示或者自动锁地图层级避免空白瓦片造成“地图崩了”的误判。实现方式很直接在zoomend事件里判断当前zoom和最大级别关系超过就map.setZoom(maxZoom)。4.3 性能优化与加载卡顿离线包虽然不依赖外网但内网环境也有性能瓶颈尤其是瓦片文件数量大机械硬盘上IOPS低的时候瓦片加载明显卡顿。我的优化经验有三点第一瓦片格式用WebP或者压缩PNG。同一区域切图WebP体积通常比PNG小60%加载速度快得多。但对老浏览器WebP兼容性差做WebGIS应用前先确认行业内用户的浏览器版本。第二利用浏览器缓存设置长期缓存头。Nginx里给/tiles/目录添加expires 30d和add_header Cache-Control public瓦片只加载一次之后全部走强制缓存。滚动地图时几乎不产生HTTP请求帧率稳定很多。第三瓦片文件按月度建立索引目录。如果你的项目需要覆盖全省范围瓦片数据可能达到几十万个小文件单个目录文件数太多时I/O寻址耗时暴涨。我建议按/tiles/{z}/{x}/{y}.png结构存放同时将瓦片打包成.mbtiles格式用本地轻量服务读取能大大减少文件操作次数。5. 写在最后的实操心得天地图离线API完整包这个东西说简单也简单说复杂也复杂。简单之处在于核心工作就是把在线依赖换成离线依赖把网络请求换成文件读取复杂之处在于地图API的功能远不止画地图那一小块坐标转换、逆地理编码、轨迹移动这些看起来不起眼的能力一旦放在离线环境里都需要一套完整的替代方案。我做这个项目最大的感受是“完整包”三个字不能只看字面意思必须站在用户真实操作路径上检查一遍用户会不会放大缩小会不会搜索地名会不会画线会不会让轨迹动起来这些操作在官网在线模式下各有各的依赖离线包每一处都要给到对应的出口。最后再分享一个小技巧不要一次性把所有瓦片打包。第一次做离线包先把部署区域裁剪到最小范围验证API全部功能跑通后再逐步扩展瓦片覆盖范围。这样即便后续踩坑排查范围也小得多。天地图API的版本更新很快离线包做好后要保留一个构建产物清单记录所用API的版本号、瓦片来源、修改了哪些源文件。有了这份清单后续升级维护才能做到心里有数。本文还有配套的精品资源点击获取
