一、离线地图由哪四部分组成

把「离线地图」拆开,实际上是四层东西叠在一起,缺一层都跑不起来。第一层是底图数据,决定地图上能看到什么: 道路、水系、建筑轮廓、行政区划、兴趣点,来源可以是 OSM 的 PBF、测绘部门的 SHP,也可以是自有的 GeoJSON 和业务点位。 第二层是样式规则,决定长什么样:陆地和水系的配色、道路分级线宽、注记字号与避让、每个要素从哪一级开始显示。

第三层是切片瓦片,决定怎么被快速读取。浏览器不会一次加载整幅地图,而是按当前视口请求若干张 256×256 的小图, 地址形如 /tiles/{z}/{x}/{y}.png。第四层是静态服务,决定这些图片怎么被前端拿到:最常见的是 Nginx 指向瓦片目录,也可以放进内网对象存储或 CDN。四层里任何一层依赖外网,整套就不算真正离线。

理解这个结构之后,「离线地图怎么做」就变成一个很具体的问题:数据从哪来、范围切到哪一级、样式怎么定、 瓦片放在哪台机器上。下面所有步骤都围绕这四层展开。

二、三条路线怎么选

常见的做法有三种,差别不在「能不能出图」,而在长期由谁维护、出了问题能不能自己解决。 先选路线再动手,比装完一堆软件再返工省时间。

路线怎么做适合谁主要代价与风险
抓取在线瓦片缓存用工具把 XYZ 在线瓦片抓成本地目录,前端改指向本地一次性的临时演示,范围很小授权与时效不可控,容易抓不全;第三方改样式后前后不一致
自建开源切片管线OSM PBF → osm2pgsql → PostGIS → 渲染服务 → 切瓦片有专职 GIS 工程师的团队链路长、组件多,样式调试和并发调优都要经验,维护成本高
一体化工具选范围、配样式、切瓦片、导出部署包,一条链路完成系统集成商、内网项目交付方需要一次性工具成本;范围和级别要在切图前规划好

判断标准很简单:只要「要长期维护」「要自己改样式」「要交付给甲方」这三条里命中任意一条, 就不适合走抓缓存路线。抓下来的瓦片你既不能改配色,也无法保证三个月后还能重新生成一份一样的数据。 反过来,如果只是想临时看一眼某块区域的效果,抓缓存反而是最快的。

三、五步落地流程

  1. 准备数据。确认坐标系与精度,WGS84、GCJ02、BD09 在入库前统一转成 WGS84, 否则整幅图会偏移几百米。检查属性字段是否够用来做标注:名称、等级、类型、编码, 缺字段的注记到后面只能显示编号。
  2. 框定范围与级别。按业务实际可视范围取最小外接矩形,不要直接按行政区全量切。 级别按屏幕像素密度和业务需求定,园区和厂区一般到 z16–z17,区县到 z15–z16,地级市到 z14–z15。 瓦片数量大约每提高一级翻四倍,先算清楚再切。
  3. 配样式。顺序是先定底(陆地、水系、绿地、建筑),再定线(高速、主干路、支路、行政界线), 最后定注记(字号、颜色、避让、起始显示级别)。深色大屏要压暗底图,把水系和道路的对比拉起来, 否则投到屏幕上会糊成一片。
  4. 切瓦片。先用低级别跑通全链路,确认目录结构、命名和前端能对上,再补高级别。 开启断点续切,中途中断不用从头来。
  5. 发布服务。Nginx 指向瓦片目录,补上缓存头和跨域头;前端把 XYZ 模板换成内网地址。 这一步的配置见下一节,可以整段复制改路径。
场景建议最高级别范围参考说明
园区 / 厂区z16–z173–20 km²能看清建筑轮廓与内部道路,适合安防与大屏
区县z15–z16500–1500 km²以道路、地名、乡镇边界为主
地级市z14–z158000–12000 km²城市轮廓与主干路,配合业务图层使用
全省示意z10–z1210 万 km² 以上只做宏观态势,不追求街区细节

四、用 Nginx 发布 XYZ 瓦片

瓦片切好之后就是一个普通目录,不需要任何 GIS 服务。假设瓦片按主题分目录,放在 /data/basemap/tiles/frost/{z}/{x}/{y}.png,下面这份配置可以直接用。

nginx.conf站点配置片段
server {
    listen 80;
    server_name map.intra.example.com;

    root /data/basemap;

    location /tiles/ {
        add_header Access-Control-Allow-Origin "*";
        add_header Cache-Control "public, max-age=604800";
        try_files $uri =404;
    }
}

几个关键点。root 指向瓦片的父目录,请求路径里的 /tiles/ 会自然映射到 子目录,中间不要再改 alias,否则很容易多一层或少一层。跨域头是为了应对前端页面和地图服务 不同源的情况,大屏项目里非常常见。缓存头能让第二次打开几乎不占带宽,瓦片本身是静态文件,可以放心设长。 如果导出的是 WebP,把前端地址里的后缀一起改掉,Nginx 不需要改。

排查技巧:用浏览器直接打开一张瓦片的完整地址,能看到图说明服务和路径都没问题; 如果看到 403,检查目录权限;如果看到 404,多半是路径多了一层主题目录,或者该级别根本没切。

五、前端接入只改一处

以 OpenLayers 为例,把在线源的地址换成本地模板即可,其他代码不动。

map.jsOpenLayers XYZ 源
const baseLayer = new ol.layer.Tile({
  source: new ol.source.XYZ({
    url: 'http://map.intra.example.com/tiles/frost/{z}/{x}/{y}.png',
    attributions: '© OpenStreetMap contributors',
  }),
})

用 Leaflet 时写法是 L.tileLayer(url, { maxZoom: 17 }),MapLibre 则用 raster source 配 tile URL。注意 maxZoom 要和实际切到的最高级别一致, 设置过大时用户缩放到没有瓦片的级别,屏幕上会出现空白格,看起来像服务挂了。

多套主题就是在同一个服务下换一个目录前缀,例如 /tiles/frost/ 和 /tiles/navy/。因为样式是切图阶段就固化的,换主题不需要重新切数据, 但要求同一份数据在切图时分别套用两套样式配置。

六、上线验收清单

  • 拔掉网线或断开外网后,清缓存刷新首屏仍能出图。
  • 概览级别、业务目标级别、最高级别三档都抽查过,没有空白格。
  • 把地图拖到范围边缘,视口外扩一圈没有大量 404。
  • 瓦片响应头带 Cache-Control 与 CORS。
  • 两台终端同时拖动和缩放,没有明显卡顿或白屏。
  • 换一套主题只需切换目录前缀,不需要重新切数据。
  • 整目录拷到另一台机器、指向新的 Nginx,能直接恢复服务。

七、最常见的五个坑

  • 坐标系没统一。GCJ02 与 WGS84 之间差几百米,叠加业务点位后整体偏移,越放大地图越明显。
  • 只切了目标级别。用户从概览缩放过来时中间级别是空的,表现为一层层白块往上跳。
  • 范围按中心点估算。拖动到边缘就出界,应该在业务范围外再留一到两级瓦片的余量。
  • 样式和数据耦合。改配色必须重新切图,多主题就无法复用数据,磁盘和时间都会翻倍。
  • 目录直接暴露但没有缓存头。首屏能用,二屏和三屏每次都要重新拉几百张图,大屏切换时明显卡。

八、常见问题

Q1 离线地图需要多大磁盘空间?

取决于范围和最高缩放级别。瓦片数量大约每提高一级翻四倍,切图前应在工具里按范围预估总量。单园区做到 z16 通常是几个 GB,地级市做到 z15 会到几十 GB 量级。

Q2 能不能直接把在线瓦片下载下来用?

技术上可以抓成本地目录,但授权、时效和覆盖范围都不可控,正式项目不建议。用自有数据或已获授权的数据自己切图,范围、级别和样式都可控,后续更新也不受第三方限制。

Q3 前端接入要改多少代码?

只改瓦片地址模板。OpenLayers、Leaflet、MapLibre 都支持自定义 XYZ 源,把在线地址换成内网地址即可,图层、交互和业务逻辑都不用动。

走到这里,一套最小可用的离线地图已经能跑了。接下来通常是两个方向:如果要放进隔离网长期运行, 看内网底图解决方案里的部署结构与验收项;如果纠结交付时给目录还是给单文件, 看MBTiles 和 XYZ 的区别。想先看效果,可以直接打开 在线预览,两套主题都是真实切出来的瓦片。