高德地图内网离线化：从瓦片下载到Leaflet部署实战

前阵子公司一个项目要部署到内网环境，业务方指着大屏说：地图这块必须保留，而且不能断网。我盯着需求书看了半天，脑子里蹦出来的思路其实已经很清晰了——高德地图离线化。

这里说的离线化，不是把手机高德APP的离线包下载下来完事，而是指在完全隔离的网络里，把一套可交互的地图应用完整跑起来。整体方案拆开来看就一句话：先把高德瓦片数据搬到内网，再用开源GIS引擎渲染这些瓦片，实现标记、弹窗、轨迹、聚合这些常用交互功能。

听起来不算复杂，但真正动手会发现里面全是细节。从瓦片下载脚本到Nginx发布，从坐标纠偏到前端引擎选型，每一步都可能踩坑。这篇文章把我从零到一做完的经验完整写出来，适合在内网、政务网、园区专网或涉密程度不高的企业内网里做地图展示的开发者参考。

1. 为什么做高德地图内网离线化

1.1 内网场景的硬约束

内网环境最直接的特点就是与外网物理隔离或逻辑隔离。业务系统部署在这样的网络里，意味着前端页面无法访问在线地图SDK，也无法请求任何外网站点。很多做惯了在线地图开发的同学，第一个反应还是引JSAPI、配Key、调接口，到了内网全被卡住。

除了网络隔离，还有几个现实问题：

• 在线版高德JS API的JS文件放在CDN上，内网访问不了。
• 即使手动把JS文件下载下来，脚本内部还会动态请求验证、定位、路况等接口，全部依赖外网。
• 内网环境多数也不允许随意开放外网访问权限，域名白名单、秘钥管理都是问题。
• 在线API有配额和计费规则，调用量大时成本压不住。

所以内网地图项目不能按在线开发的思路来做。你想保留高德地图的视觉效果和交互体验，就得把地图数据整体“搬”进来，同时把渲染和交互能力也全部本地化。

1.2 技术选型：瓦片方案、离线SDK还是自绘

当时我对比了三条路线：高德离线SDK、自绘地图、瓦片方案。

高德官方提供的离线SDK主要面向Android、iOS原生应用，可以在端侧下载城市离线包。但我们的项目是Web大屏，官方JS API并没有正式离线版。有人试过把JS API的脚本抓到本地，再通过代理把运行时请求转发到内网模拟，但高德JS内部还依赖很多在线服务接口，一旦某个请求失败，地图渲染就会出问题。维护成本太高，容易翻车。

自绘地图这条路最可控，但需要自己准备底图数据、道路数据、POI数据，还要做风格渲染，项目周期根本不允许。而且没有专业美工调出来的地图风格很难看，业务方大概率不会接受。

瓦片方案是目前最务实的做法：把高德地图已经渲染好的图片瓦片按层级预先下载到本地，然后通过Nginx发布成静态文件服务，前端用开源引擎加载这些瓦片。优点很明显：视觉风格和高德在线保持一致，地图数据量可控，渲染性能高，交互能力用开源轮子补齐。

1.3 整体链路设计

整个链路分四段：

1. 确认需要的区域范围和最大缩放级别。
2. 用脚本把该范围内每个级别的高德瓦片批量下载到本地。
3. 在内网部署Nginx或其他静态文件服务，把瓦片目录发布出去。
4. 前端页面用Leaflet等开源GIS引擎加载内网瓦片服务，叠加业务图层和交互功能。

这套链路的关键点在于第2步的瓦片坐标换算、第3步的发布代理，以及第4步的坐标体系一致性问题。下面逐个展开。

2. 动手前先搞懂瓦片规则与坐标体系

2.1 XYZ瓦片到底怎么编号

很多同学第一次接触瓦片时，会被一堆数字搞得头晕。其实原理很简单：地图服务商把全球地图按金字塔模型切成很多张正方形小图片，每张就是一个瓦片。第0级通常只有1张或2张瓦片；越往下放大，级别越高，瓦片数量越多。

这里用OpenStreetMap推广开的XYZ规则，这是目前WebGIS最通用的瓦片寻址方式：

• z表示缩放级别。
• x表示瓦片所在列，从西到东，从0开始。
• y表示瓦片所在行，从北到南，从0开始。

高德地图瓦片在Web端也是按这个规则组织的，只是不同数据源的代号和URL模板有所不同。你拿到瓦片服务的地图URL后，通常只需要把{z}、{x}、{y}三个参数替换成实际数值就能直接请求到图片。

比如某一级某个位置的瓦片请求，URL模板大概是：

{你的数据源地址}/mapstyle/{z}/{x}/{y}.png?param=...

具体域名和参数每个项目不一样，核心是记住替换z/x/y。建议在实际写脚本前，先在浏览器地址栏里手改几组数字，确认这套URL模板能正常返回图片，再动手写批量下载程序。

2.2 经纬度换算瓦片编号：公式与代码

判断一个地理坐标落在哪个瓦片里，需要做一次坐标换算。公式看起来有一点数学味道，但写起来很固定，可以直接抄：

n = 2^z x = int((lng + 180.0) / 360.0 * n) y = int((1.0 - ln(tan(lat_rad) + 1 / cos(lat_rad)) / pi) / 2.0 * n)

其中lat_rad是纬度的弧度值。这个y公式就是Web Mercator投影的反算，不用理解太深，知道它是把地球球面坐标映射到平面瓦片网格上就行。

代码实现如下：

import math def lon_lat_to_tile(lon, lat, zoom): lat_rad = math.radians(lat) n = 2 ** zoom x = int((lon + 180.0) / 360.0 * n) y = int((1.0 - math.asinh(math.tan(lat_rad)) / math.pi) / 2.0 * n) return x, y

注意：这里用math.asinh是为了代码简洁。这个函数等价于上文公式里的ln(tan(φ) + sec(φ))，只是Math库里的反双曲正弦刚好有这个性质，写起来更紧凑。

实际下载某个矩形区域的瓦片时，很多人会写出“先算左上角瓦片，再算右下角瓦片，然后双重循环遍历”的逻辑。这里有一个必须注意的细节：瓦片y方向是自北向南递增的，所以左上角的纬度更大，右上角经度更大。也就是说，取范围时要按下面这种方式算：

def collect_tiles(min_lon, min_lat, max_lon, max_lat, zoom): x1, y1 = lon_lat_to_tile(min_lon, max_lat, zoom) # 注意纬度用最大纬度 x2, y2 = lon_lat_to_tile(max_lon, min_lat, zoom) # 这里用最小纬度 tiles = [] for x in range(min(x1, x2), max(x1, x2) + 1): for y in range(min(y1, y2), max(y1, y2) + 1): tiles.append((zoom, x, y)) return tiles

第一次写这个逻辑时很容易把左上角和右下角的坐标算反，导致下载回来的瓦片错位或缺一大片。把min和max都做一遍比较，再用range遍历，是最稳妥的写法。

2.3 GCJ-02、WGS-84和Web Mercator的纠葛

这是离线地图开发里最大的坑，也是很多人做得好好的项目突然出现几百米偏移的根本原因。

简单说，国内商用地图服务商（包括高德）在对外提供地图数据时，坐标并不是GPS原生的WGS-84坐标，而是经过一次非线性偏移的GCJ-02坐标。高德瓦片本身已经按GCJ-02做了纠偏，所以在高德自己的前端引擎里加载，用户感觉不到问题。

但如果换成Leaflet这类开源引擎直接加载高德瓦片，底图本身是GCJ-02的；而你的业务数据如果是从GPS设备、第三方传感器拿到的WGS-84坐标，直接打到地图上就会偏移。偏移量不是固定值，在北京市区通常几百米，方向也不完全一致，无法通过简单加减修正。

解决办法有两种：一是业务设备出数时直接做一次坐标转换，把WGS-84转成GCJ-02再入库；二是在前端渲染前统一转换。前者更好，因为数据入库后是干净的。

后面的章节我会给出一段可用的转换代码。这里先记住结论：数据坐标体系必须和高德瓦片保持一致，统一用GCJ-02，偏差问题就消失。

3. 核心实操：编写瓦片下载脚本

3.1 确定下载范围、级别与体量

在下脚本之前，先想清楚要下载哪几级瓦片。

内网项目常见的地图展示场景是城市级或园区级。整体覆盖可以考虑10到12级看全局，业务聚焦区域下载到15级甚至17级。但级别越高，瓦片数量呈4倍增长，不是线性的。

以北京六环内区域为例，我做过一个粗略估算：

以上是经验估值，具体体积取决于瓦片内容复杂度和图片压缩率。地图内容密集的区域单张瓦片可能到80KB，而郊区纯色瓦片可能只有10KB。下载前先按这个量级估算好硬盘空间。

不建议一上来就全级别全范围下载。先下载低级别观察效果，再逐步增加范围和级别。否则脚本写错了或者范围框大了，带宽和时间成本都很浪费。

3.2 Python脚本落地：完整实现与踩坑

下载脚本我建议用Python写，生态成熟，requests加concurrent.futures就能搞定并发。贴一段我实际用下来的结构：

import math import os import time import requests from concurrent.futures import ThreadPoolExecutor, as_completed HEADERS = { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36", "Referer": "https://your.site/", # 按数据源要求设置 } # 瓦片URL模板，具体按项目数据源填充 URL_TEMPLATE = "https://your-tile-host/{z}/{x}/{y}.png" def lon_lat_to_tile(lon, lat, zoom): lat_rad = math.radians(lat) n = 2 ** zoom x = int((lon + 180.0) / 360.0 * n) y = int((1.0 - math.asinh(math.tan(lat_rad)) / math.pi) / 2.0 * n) return x, y def download_one(z, x, y, save_dir): save_path = os.path.join(save_dir, str(z), str(x), f"{y}.png") if os.path.exists(save_path) and os.path.getsize(save_path) > 0: return True url = URL_TEMPLATE.format(z=z, x=x, y=y) for attempt in range(3): try: resp = requests.get(url, headers=HEADERS, timeout=10) if resp.status_code == 200: os.makedirs(os.path.dirname(save_path), exist_ok=True) with open(save_path, "wb") as f: f.write(resp.content) return True elif resp.status_code == 429: time.sleep(2 * (attempt + 1)) except Exception: time.sleep(1) return False def download_region(min_lon, min_lat, max_lon, max_lat, zoom, save_dir): x1, y1 = lon_lat_to_tile(min_lon, max_lat, zoom) x2, y2 = lon_lat_to_tile(max_lon, min_lat, zoom) tasks = [] for x in range(min(x1, x2), max(x1, x2) + 1): for y in range(min(y1, y2), max(y1, y2) + 1): tasks.append((zoom, x, y)) failed = [] with ThreadPoolExecutor(max_workers=8) as pool: futures = {pool.submit(download_one, *task): task for task in tasks} for future in as_completed(futures): task = futures[future] try: if not future.result(): failed.append(task) except Exception: failed.append(task) if failed: print(f"失败数量: {len(failed)}") with open("failed_tiles.txt", "w") as f: for z, x, y in failed: f.write(f"{z}/{x}/{y}\n") else: print("全部下载完成")

这段代码里有几个当时踩坑后加进去的点，值得讲解。

第一是重试机制。有些瓦片服务对高频请求会返回429限流，重试时加退避时间，否则连续下载几千张瓦片时很容易被临时封禁。第二是断点续传。脚本判断文件存在且大小不为0就跳过，避免中途挂了要全部重新下载。第三是失败列表落盘。下载完成后检查failed_tiles.txt，再针对失败项单独补拉，比在终端里翻日志高效得多。

并发数建议控制在8到16之间。开太高容易被数据源限流，开太低下载几万张瓦片会等很久。带宽和内网部署阶段，通常8线程是平衡点。

3.3 内网Python环境的准备与依赖离线安装

下载脚本理论上可以在有网环境跑完再把瓦片摆渡进内网，但实际操作中，内网服务器往往也需要跑数据处理程序，比如瓦片重命名、目录整理、格式清洗。这时候内网机器的Python环境就要提前准备好。

内网Linux机器常见的坑是Python版本过旧。很多国产化Linux服务器自带的还是Python 2.7或者3.6，跑现代脚本会报语法错误。优先用源码编译安装新版Python，步骤不复杂：

# 先确认编译工具链 yum install -y gcc gcc-c++ make openssl-devel zlib-devel bzip2-devel readline-devel sqlite-devel libffi-devel # 下载Python源码后编译 ./configure --prefix=/usr/local/python3.11 --enable-optimizations make && make install ln -s /usr/local/python3.11/bin/python3.11 /usr/local/bin/python3 ln -s /usr/local/python3.11/bin/pip3.11 /usr/local/bin/pip3

编译前务必装上openssl-devel和libffi-devel，否则pip会报ssl相关错误，新版Python也装不上requests这些包。

依赖包离线安装也很简单，在外网机器上执行：

pip download -d /tmp/pkgs requests

然后把整个pkgs目录拷进内网，内网执行：

pip install --no-index --find-links=/tmp/pkgs requests

这里的--no-index参数很关键，表示不访问PyPI，只从本地目录查找安装包。把requests、urllib3、charset-normalizer这些常见包全部下载好，后续脚本就不会再缺依赖。

4. 用Nginx发布本地瓦片服务

4.1 目录结构与命名校验

瓦片下载完成后，要检查目录是否按标准路径组织。Nginx静态服务的目录结构需要和瓦片URL对齐。一个规范的目录结构如下：

/data/map_tiles/ └── 15/ ├── 26000/ │ ├── 13000.png │ ├── 13001.png │ └── ... ├── 26001/ │ └── ... └── ...

也就是z目录下面套x目录，再往下是y.png文件。Leaflet等前端引擎发请求时会自动替换URL里的{z}/{x}/{y}，所以目录结构必须严格匹配，多一层少一层都会404。

有时候下载脚本会以不同规则保存，比如把z/x/y写反了，或者文件名缺少扩展名。建议下载完成后写一个小脚本，随机抽几十个路径检查文件是否存在以及大小是否正常，避免部署到Nginx才发现一堆404。

4.2 Nginx配置与缓存策略

内网访问量通常不会非常大，但大屏项目往往有多个终端同时拉图，Nginx配置得当可以省很多后端压力。核心配置如下：

server { listen 8000; server_name map.internal; location /tiles/ { alias /data/map_tiles/; access_log off; expires 30d; add_header Cache-Control "public, max-age=2592000"; try_files $uri =404; } location / { root /data/map_web; index index.html; try_files $uri $uri/ /index.html; } }

瓦片是静态不变的文件，开启expires让浏览器缓存一个月，可以极大减少重复请求。access_log建议关掉，否则几天下来日志文件就能积累几GB，全是瓦片请求记录。

还要注意location的alias与root区别。alias会把location匹配到的路径替换成指定目录，所以/tiles/15/1/2.png会映射到/data/map_tiles/15/1/2.png。如果用root，Nginx会把完整URI拼在root目录后面，变成/data/map_tiles/tiles/15/1/2.png，目录结构就错了。这是配置静态瓦片服务时最容易犯的错。

如果前端应用部署在另一台机器，需要在瓦片服务的server里加跨域头：

add_header Access-Control-Allow-Origin *;

否则浏览器会拦截跨域图片请求，地图白屏。

5. 前端交互功能集成：Leaflet版离线地图实战

5.1 引擎选择的思路

前端引擎我首选Leaflet。相比OpenLayers，Leaflet更轻，配置简单，开发效率高；相比MapLibre GL，Leaflet对标准瓦片服务的兼容性更好，学习成本也更低。项目只做2D地图场景，Leaflet足够用。

既然瓦片数据是高德的，为什么不尝试强行加载高德JS API？前面提到过，高德JS API离线后内部很多接口不可用。即使勉强让底图渲染出来了，标记点、气泡弹窗这些能力还是依赖它的DOM和事件系统，出问题很难排查。用Leaflet替换后，渲染和交互全部本地化，只把高德当作纯瓦片数据源，这个解耦让项目稳定很多。

5.2 初始化和基础交互

初始化地图，加载本地Nginx上的瓦片服务：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>内网离线地图</title> <link rel="stylesheet" href="assets/leaflet/leaflet.css" /> <style> html, body, #map { width: 100%; height: 100%; margin: 0; } </style> </head> <body> <div id="map"></div> <script src="assets/leaflet/leaflet.js"></script> <script> const map = L.map('map', { center: [39.9042, 116.4074], zoom: 12, minZoom: 3, maxZoom: 17 }); L.tileLayer('http://map.internal:8000/tiles/{z}/{x}/{y}.png', { maxZoom: 17, attribution: 'Internal Map Service', keepBuffer: 4, updateWhenIdle: false }).addTo(map); </script> </body> </html>

这里有两个参数值得说明。keepBuffer: 4表示地图周围多加载4圈瓦片，让拖动时不出现白边闪烁。updateWhenIdle: false则是让地图在缩放或平移过程中就持续加载新瓦片，而不是等动画完全停下来才加载。内网带宽低时，这两项对体验提升很明显。

Leaflet的缩放、拖拽、双击放大、滚轮缩放这些交互默认就带，不需要额外配置。如果不希望用户拖动到没有瓦片的区域，可以设置minZoom/maxZoom，超出范围的级别前端直接不允许浏览。

5.3 业务场景：标记、弹窗、轨迹与聚合

内网地图项目最常见的需求是打点展示设备位置。用Marker加Popup就能实现：

const marker = L.marker([39.9042, 116.4074]).addTo(map); marker.bindPopup(` <b>设备编号：BJ-JK-0001</b><br> 状态：正常运行<br> 最近上报：2025-06-12 10:33 `);

如果点位数量几十上百，建议用layerGroup统一管理：

const markerLayer = L.layerGroup().addTo(map); function renderDevices(devices) { markerLayer.clearLayers(); devices.forEach(d => { L.marker([d.lat, d.lng]) .bindPopup(d.name) .addTo(markerLayer); }); }

上千个点位时，直接打Marker会把页面卡死。这时候用Leaflet.markercluster插件做聚合。把插件的js和css下载到本地，通过相对路径引入：

const clusterLayer = L.markerClusterGroup({ maxClusterRadius: 40 }); devices.forEach(d => { clusterLayer.addLayer(L.marker([d.lat, d.lng])); }); map.addLayer(clusterLayer);

聚合插件的效果是：地图缩放级别低时把相近的点聚合成一个数字气泡，放大后气泡拆开，交互体验接近在线地图。

轨迹展示是另一个高频需求。用L.polyline画线：

const trackPoints = [ [39.9010, 116.4030], [39.9020, 116.4050], [39.9042, 116.4074], [39.9060, 116.4110] ]; const trackLine = L.polyline(trackPoints, { color: '#ff6600', weight: 3, opacity: 0.9 }).addTo(map); map.fitBounds(trackLine.getBounds());

配合L.circleMarker标注轨迹上的关键节点，能做出很直观的车辆或人员轨迹回放页面。

5.4 坐标纠偏与数据兼容

前面说过，GPS原始坐标是WGS-84，高德瓦片是GCJ-02。如果业务数据存的是WGS-84，必须在前端或后端做一次转换。我贴一份前端JavaScript的通用转换函数，来自开源社区，实测过国内主流城市可用：

function transformLat(x, y) { let ret = -100.0 + 2.0 * x + 3.0 * y + 0.2 * y * y; ret += 0.1 * x * y + 0.2 * Math.sqrt(Math.abs(x)); ret += (20.0 * Math.sin(6.0 * x * Math.PI) + 20.0 * Math.sin(2.0 * x * Math.PI)) * 2.0 / 3.0; ret += (20.0 * Math.sin(y * Math.PI) + 40.0 * Math.sin(y / 3.0 * Math.PI)) * 2.0 / 3.0; ret += (160.0 * Math.sin(y / 12.0 * Math.PI) + 320 * Math.sin(y * Math.PI / 30.0)) * 2.0 / 3.0; return ret; } function transformLng(x, y) { let ret = 300.0 + x + 2.0 * y + 0.1 * x * x; ret += 0.1 * x * y + 0.1 * Math.sqrt(Math.abs(x)); ret += (20.0 * Math.sin(6.0 * x * Math.PI) + 20.0 * Math.sin(2.0 * x * Math.PI)) * 2.0 / 3.0; ret += (20.0 * Math.sin(x * Math.PI) + 40.0 * Math.sin(x / 3.0 * Math.PI)) * 2.0 / 3.0; ret += (150.0 * Math.sin(x / 12.0 * Math.PI) + 300.0 * Math.sin(x / 30.0 * Math.PI)) * 2.0 / 3.0; return ret; } function wgs84ToGcj02(lng, lat) { const a = 6378245.0; const ee = 0.006693421622965943; let dLat = transformLat(lng - 105.0, lat - 35.0); let dLng = transformLng(lng - 105.0, lat - 35.0); const radLat = lat / 180.0 * Math.PI; let magic = Math.sin(radLat); magic = 1 - ee * magic * magic; const sqrtMagic = Math.sqrt(magic); dLat = (dLat * 180.0) / ((a * (1 - ee)) / (magic * sqrtMagic) * Math.PI); dLng = (dLng * 180.0) / (a / sqrtMagic * Math.cos(radLat) * Math.PI); return [lng + dLng, lat + dLat]; }

调用方式很简单：把GPS采集的原始经纬度传给wgs84ToGcj02，返回的坐标就是能和底图对齐的点。手机端定位上报的数据，以及在苹果设备上偶发的位置偏差问题，很多都是因为拿了WGS-84坐标没转换就上图，导致点位看着偏到别人家楼顶。

这里要注意：纬度值范围内不能把海域计算跳过，否则转换精度下降。实际使用中，只要坐标在国土地理范围内，统一走这个函数即可。

6. 常见问题排查与性能调优实录

6.1 高频问题速查表

做离线地图项目过程中，我遇到最多的一批问题，整理成表格方便快速对照：

瓦片404是最常见的，拿到路径后先手动在浏览器打开瓦片URL，确认Nginx返回的是图片而不是错误页。如果返回403，大概率是没有配置跨域头或路径权限有问题。

6.2 性能调优三板斧

第一板斧是瓦片体积控制。从在线数据源下载的图片已经比较优化，但部分瓦片仍然有压缩空间。批量做一次pngquant压缩，地图底图的瓦片体积能降20%到40%。Nginx端再开启gzip，传输体积进一步下降。压缩前先备份，对比压缩后有无肉眼可见的清晰度损失，有些底图文字细节会被压糊。

第二板斧是前端缓存策略。Leaflet对瓦片有内存缓存，配合浏览器HTTP缓存，第二次打开页面时大部分瓦片直接从本地缓存读取，请求量会少很多。如果项目里地图切换频率很高，可以做一个内存中的瓦片缓存池，简单做法是维护一个Map对象，key用z/x/y拼接，value存Image对象，避免重复创建Image导致内存上涨。

第三板斧是分层加载。内网项目如果地图资源有几百GB，不可能全部发布到Nginx后每个终端都去拉全量数据。常见做法是分级别存储：常用级别放本地，不常用级别放内网NAS或对象存储，Nginx通过内网回源缓存。但因为内网一般没有外网回源条件，更现实的方案是按业务区域裁切范围，区域外不下载，区域内尽量覆盖到需要的最高级别。

还有一个容易忽略的坑：如果内网机器配置不高，渲染大屏时不要同时开太多Leaflet实例。多个页签或者多个大屏都初始化地图，内存占用会叠加。切屏前主动调map.remove()销毁地图实例，而不是简单隐藏div。这个排查起来很费劲，最好在代码里就养成清理的习惯。

结尾

这套内网高德地图离线化方案做完之后，我的直观感受是：真正花时间的不是技术实现本身，而是把瓦片数据、坐标体系和前端工程之间那层说不清道不明的关联彻底搞清楚。尤其是坐标转换，内网项目里数据来源五花八门，有GPS设备上报的，有标定过的，有从第三方平台导出的，只要有一个环节忘了统一到GCJ-02，地图上就必然出现肉眼可见的偏移。

最后再分享一个小技巧：瓦片数据下载完成后，别急着清理有网环境的脚本和中间文件。项目上线后业务范围大概率会调整，今天只要北京城区，明天可能就要扩展到天津。把下载脚本、范围配置、失败列表都纳入版本管理，下次扩展时重新跑一遍脚本，只增量下载就能快速补齐数据，不用从头再来。