简介地图瓦片下载工具AZMap 4.9是一款专业的地图数据获取软件基于Web GIS的瓦片分割技术帮助用户从Google Maps、Bing Maps、OpenStreetMap等在线服务高效下载任意区域、多个层级的地图瓦片。它适用于需要离线地图的户外探险、GIS空间分析、地图制图、网络地图服务备份以及地图应用开发等场景尤其方便网络条件有限时的数据获取。压缩包内共841个文件主要包含JavaScript脚本、投影定义文件prj、PNG格式瓦片图片、DLL动态库、CSV地理数据以及必要的运行配置压缩后总大小约47.15MB整体结构清晰便于按需提取使用。该工具核心程序为AZMap.exe版本4.9同时配有任务索引文件azdb、地区地理数据库如河北数据以及多个批处理脚本如初始化IIS、创建/删除服务器等用户可直接运行程序通过界面设置地图源、层级范围、坐标系统和输出格式也可参考内置脚本和配置文件进行二次定制。目前已有1210人学习下载是地理信息相关从业者和爱好者获取瓦片数据、搭建离线地图服务的实用工具。1. 地图瓦片下载工具到底在解决什么为什么截图拼图不是选项地图瓦片下载工具简单说就是把在线地图按“层级-横-纵”的网格编号规则批量抓取小方块图片到本地。很多人第一反应是截图真正做离线底图的人不会这么干截图没有坐标信息拼接后无法对齐更没法按缩放级别切换。这个工具解决的问题是给定一个矩形范围自动算出覆盖这个范围所有层级的瓦片编号并发下载、断点续传、失败重试最后得到一套能在本地直接使用的瓦片目录。适用人群很明确GIS 开发、需要离线底图的业务系统、以及做数据预处理的技术人员。它的核心不是“爬虫”而是坐标系换算和并发调度这两件事做明白工具就算立住了。2. 先搞懂瓦片编号与坐标系z/x/y 背后的 Web Mercator 换算下载工具的输入是经纬度范围输出是一堆编号。如果不懂编号规则下载器在你眼里就是个黑匣子参数填错、y 方向反了、层级算多了全要等跑完才发现。所以先花一章把编号规则和换算逻辑讲透后面写代码才有把握。2.1 XYZ 编号规则为什么一张地图会被切成 2^z 个小方块在线地图把世界地图切成无数个 256x256 的小图片每一张叫一张瓦片。z 代表缩放层级z0 时整个世界地图是一张 256x256 的图z1 时切成 2x2 共 4 张z2 时是 4x4 共 16 张。规律是层级为 z 时地图被切成 2^z 行、2^z 列。x 表示从左往右数的列号y 表示从上往下数的行号这就是最常见的 XYZ 规则绝大多数在线瓦片服务都遵循它。这套规则背后是 Web Mercator 投影。它把地球按经纬度网格投影成一个正方形平面纬度范围大约在正负 85.05 度之间超出这个范围的地图会被切掉。为什么下载工具必须知道它因为把经纬度换算成瓦片行列号时纬度方向用的是反双曲正弦函数不是简单的线性除法。很多初版工具在这里翻车直接拿经纬度除以 360 再乘 2^z低纬度区域看着没问题高纬度地区就越偏越远。还要注意一个隐藏规则XYZ 的 y 从顶部开始数而另一种叫 TMS 的规则是 y 从底部开始数。同一个经纬度点在两种规则下算出的 y 编号完全相反。下载工具里通常有个“翻转 Y”开关选错了拼出来就是上下颠倒。判断方法很简单下载一张已知位置的瓦片比如北纬 39.9 度、东经 116.4 度附近的一个点看看显示内容对不对再做全量下载。2.2 经纬度换算成瓦片行列号一个不需要 GIS 依赖的 Python 函数先用纯标准库写一个换算函数不依赖任何 GIS 库这样在任何 Python 环境里都能跑也方便理解公式本身。import math def lonlat_to_tile(lon, lat, zoom): # Web Mercator 有效纬度范围约是正负 85.05 度 lat max(-85.05, min(85.05, lat)) n 2 ** zoom # x 方向是线性映射经度 -180~180 映射到 0~2^z x (lon 180.0) / 360.0 * n # y 方向用 Web Mercator 投影公式asinh(tan(lat_rad)) lat_rad math.radians(lat) y (1.0 - math.asinh(math.tan(lat_rad)) / math.pi) / 2.0 * n return int(x), int(y) def calc_tile_range(west, south, east, north, zoom): # 西南角算出的是 x 最小、y 最大东北角算出的是 x 最大、y 最小 x_min, y_max lonlat_to_tile(west, south, zoom) x_max, y_min lonlat_to_tile(east, north, zoom) # 因为 y 从顶部开始数纬度越高 y 越小这里必须交换一次 if y_min y_max: y_min, y_max y_max, y_min return x_min, x_max, y_min, y_max逻辑说明lonlat_to_tile 先限制纬度范围避免投影公式在极区算出无效值。x 方向是线性映射经度从 -180 到 180 对应 x 从 0 到 2^z。y 方向是标准的 Web Mercator 逆变换公式里用了 asinh 而不是 log 加 cos 的写法两种写法数学上等价asinh 在数值上更稳定也不容易出现除零。参数说明west、south 是范围西南角的经纬度east、north 是东北角的经纬度。calc_tile_range 返回的 x_min、x_max、y_min、y_max 已经按 XYZ 规则整理好可以直接用来生成下载任务。这里有个容易忽略的点计算结果是“覆盖范围”而不是“完整落在范围内”的瓦片集合边缘瓦片只覆盖到边界的一部分。所以实际下载时我会把范围外扩 1 到 2 张瓦片宁愿多下一点也不要拼图时发现边缘缺一条。这个习惯后面拼图时会解释原因。3. Python 实现最小可用版从串行下载到并发提速的完整代码原理讲完开始写能跑的东西。我用 Python 标准库实现不引入任何第三方依赖下载逻辑用 urllib.request。先把单线程版本跑通再改造成线程池并发这样新手能看清楚每一步在干什么熟手也能直接拿代码当模板改。3.1 串行版本30 行代码把指定范围瓦片落盘先写一个下载单张瓦片的函数顺便解决掉“重复下载”和“目录结构”两个基础问题。import os import urllib.request TILE_URL https://tiles.example.com/{z}/{x}/{y}.png HEADERS {User-Agent: Mozilla/5.0 (study script)} OUTPUT_DIR tiles def download_one(z, x, y): path f{OUTPUT_DIR}/{z}/{x}/{y}.png # 已存在且文件非空视为已下载直接跳过 if os.path.exists(path) and os.path.getsize(path) 0: return True os.makedirs(os.path.dirname(path), exist_okTrue) url TILE_URL.format(zz, xx, yy) req urllib.request.Request(url, headersHEADERS) # timeout 设 15 秒防止个别瓦片卡死整个任务 with urllib.request.urlopen(req, timeout15) as resp, open(path, wb) as f: f.write(resp.read()) return True逻辑说明下载前先检查文件是否存在并且大于 0 字节这是最简单的断点续传。很多工具只判断“文件存在”就跳过结果进程被强杀后留下一堆 0 字节文件重跑时全部跳过拼图才发现缺片。判断非空这个习惯建议直接刻进肌肉记忆。目录结构按 z/x/y.png 组织和 URL 路径保持一致之后做本地瓦片服务时可以直接把目录丢给静态服务器。参数说明TILE_URL 里的 {z}/{x}/{y} 是占位符format 会依次替换。HEADERS 里的 User-Agent 必须带有些瓦片服务对没有 UA 的请求直接返回 403。timeout 15 秒是保守值内网瓦片服务可以降到 5 秒公网服务建议保持 15 秒以上。串行调用很简单def main(): # 示例z10x 从 300 到 310y 从 400 到 410 for z in [10]: for x in range(300, 311): for y in range(400, 411): download_one(z, x, y) print(fz{z} done) if __name__ __main__: main()这个版本能跑但速度很慢。121 张瓦片如果每张耗时 0.3 秒串行要接近 40 秒。真实项目通常要下几万张串行得跑到天荒地老。下一步改成并发。3.2 并发版本线程数、超时与重试的推荐参数瓦片下载是典型的 IO 密集型任务瓶颈在网络等待不在 CPU。Python 的多线程在这里正好合适直接上 ThreadPoolExecutor代码改动量很小。import time import random from concurrent.futures import ThreadPoolExecutor, as_completed def download_one_with_retry(z, x, y, max_retry3): for attempt in range(max_retry): try: # 每张瓦片下载前随机等待 0.1~0.3 秒降低请求特征 time.sleep(random.uniform(0.1, 0.3)) download_one(z, x, y) return True except Exception as e: # 指数退避第 1 次失败等 1 秒第 2 次等 2 秒第 3 次等 4 秒 wait 2 ** attempt print(f[retry] z{z} x{x} y{y}, attempt{attempt 1}, wait{wait}s, err{e}) time.sleep(wait) return False def download_many(tasks, workers8): failed [] with ThreadPoolExecutor(max_workersworkers) as pool: future_map { pool.submit(download_one_with_retry, z, x, y): (z, x, y) for z, x, y in tasks } for fut in as_completed(future_map): z, x, y future_map[fut] if not fut.result(): failed.append((z, x, y)) return failed逻辑说明download_many 把任务列表全部提交给线程池as_completed 遍历结果失败的记录到 failed 列表。download_one_with_retry 在原有下载逻辑外包了一层重试每次失败后等待时间按 2 的幂次增长1 秒、2 秒、4 秒避免失败后立刻重试导致的服务端压力叠加。参数说明max_workers8 是保守起点。太慢浪费带宽太快容易被服务端限流甚至封 IP8 是多数公网瓦片服务能接受的并发数。如果你访问的是内网自建瓦片服务可以调到 16 或 32如果是公网商业服务建议从 4 试起。random.uniform(0.1, 0.3) 这行是经验之谈固定间隔的请求很容易被识别成脚本加一点随机抖动能把触发限流的概率降一个量级。并发版本跑完后把 failed 列表打印出来看看。如果失败率超过 1%先别急着全量下载多半是并发太高或者请求头不全先小范围试 200 张摸清服务端的脾气再铺开。这一步能省下大量重跑时间。4. 工程化必做的三件事失败重试、频率控制与断点续传单机和并发的代码能跑通但离“工具”还差得远。真实下载任务动辄几万张瓦片跑几个小时中途网络抖动、服务端限流、进程被杀都会发生。这章把配置管理、频率控制和失败恢复三件事补齐工具才算有工程化的样子。4.1 用配置对象统一范围、层级与并发参数参数散落在代码里没法维护。我把所有可调项收敛到一个配置对象里命令行也好、配置文件也好最终都转成这个对象传给下载逻辑。from dataclasses import dataclass dataclass class DownloadConfig: west: float 116.0 # 范围西边经度 south: float 39.0 # 范围南边纬度 east: float 117.0 # 范围东边经度 north: float 40.0 # 范围北边纬度 min_zoom: int 5 # 最小层级 max_zoom: int 15 # 最大层级 workers: int 8 # 并发线程数 timeout: int 15 # 单张瓦片超时秒数 max_retry: int 3 # 最大重试次数 output_dir: str tiles # 输出目录 wait_range: tuple (0.1, 0.3) # 随机等待区间 def generate_tasks(cfg): tasks [] for z in range(cfg.min_zoom, cfg.max_zoom 1): x_min, x_max, y_min, y_max calc_tile_range( cfg.west, cfg.south, cfg.east, cfg.north, z) # 外扩 1 张瓦片边缘才不会被裁掉 x_min max(0, x_min - 1) x_max min(2 ** z - 1, x_max 1) y_min max(0, y_min - 1) y_max min(2 ** z - 1, y_max 1) for x in range(x_min, x_max 1): for y in range(y_min, y_max 1): tasks.append((z, x, y)) return tasks逻辑说明generate_tasks 把经纬度范围按每个层级分别换算成任务列表。外扩一张瓦片那两行是踩坑踩出来的不扩的边缘瓦片在拼接时往往缺一条边。x_max 和 y_max 的上限是 2^z - 1因为编号从 0 开始超过这个值就超出世界地图范围了。参数建议min_zoom 到 max_zoom 跨度越大任务量增长越快。层级每加 1瓦片数量是上一层的 4 倍。z15 覆盖一个普通地级市范围大约要几万张z18 就是几百万张级别磁盘空间和下载时长要提前算清楚。4.2 失败重试与频率控制别让单 IP 触发限流网络请求的失败是常态不是意外。我一般把频率控制和重试逻辑封装在一起这样调用方不需要关心细节。import time import random class TileDownloader: def __init__(self, cfg: DownloadConfig): self.cfg cfg self.failed [] def download_one(self, z, x, y): path f{self.cfg.output_dir}/{z}/{x}/{y}.png if os.path.exists(path) and os.path.getsize(path) 0: return True os.makedirs(os.path.dirname(path), exist_okTrue) url TILE_URL.format(zz, xx, yy) req urllib.request.Request(url, headersHEADERS) wait random.uniform(*self.cfg.wait_range) time.sleep(wait) with urllib.request.urlopen(req, timeoutself.cfg.timeout) as resp, open(path, wb) as f: f.write(resp.read()) return True def run(self, tasks): with ThreadPoolExecutor(max_workersself.cfg.workers) as pool: future_map { pool.submit(self._with_retry, z, x, y): (z, x, y) for z, x, y in tasks } for fut in as_completed(future_map): z, x, y future_map[fut] if not fut.result(): self.failed.append((z, x, y)) return self.failed def _with_retry(self, z, x, y): for attempt in range(self.cfg.max_retry): try: return self.download_one(z, x, y) except Exception as e: wait 2 ** attempt print(f[retry] z{z} x{x} y{y}, attempt{attempt 1}, wait{wait}s) time.sleep(wait) return False逻辑说明把重试和下载拆成两个方法_with_retry 只负责重试策略download_one 只负责单张下载职责清楚。随机等待放在下载前而不是放在重试前这样整个任务流的请求间隔天然就是抖动的不会出现整批线程同时请求再同时休眠的脉冲式流量。参数说明wait_range 默认 0.1 到 0.3 秒对应单线程每秒钟约 3 到 10 张。8 个线程时整体速度大约每秒 30 到 50 张这个速度对大多数公网服务是安全的。如果遇到严格限流的服务端把 workers 降到 4、wait_range 调到 0.3 到 0.6大多数 403 问题都能缓解。4.3 断点续传把 failed.csv 当成后悔药跑了几十分钟突然断网任务失败记录得留下来不然重跑又是几十分钟。我习惯把失败任务写进 CSV下次启动时先读这个文件。def write_failed(failed, pathfailed.csv): with open(path, w) as f: for z, x, y in failed: f.write(f{z},{x},{y}\n) def load_failed(pathfailed.csv): tasks [] if os.path.exists(path): with open(path) as f: for line in f: line line.strip() if not line: continue z, x, y map(int, line.split(,)) tasks.append((z, x, y)) return tasks逻辑说明write_failed 把失败的三元组按行写入 CSVload_failed 在下次启动时读回来重新丢进线程池。这个文件就是你的后悔药。配合 download_one 里的“存在且非空就跳过”逻辑重跑只补缺失的瓦片不会重复下载已完成的部分。使用建议跑完一次全量任务后把 failed.csv 加载进来单独重试两三轮直到列表为空。如果某几张瓦片反复失败多半是服务端本身缺图不是网络问题直接记录到 missing.txt 里拼图时做特殊处理。断点续传的粒度到单张瓦片就足够了不需要做到字节级断点那对图片下载毫无意义。5. 瓦片下载的常见问题与排查403、黑块、坐标偏移与零字节这章把我在实际下载中遇到最多的问题集中列出来按“现象、原因、解决”的格式写。这些问题单看都像玄学其实背后的原因非常固定排查顺序也有规律可循。5.1 先看现象对照表5 类最常翻车的问题现象可能原因解决方向下载到一半开始大量 403请求频率太高或请求头不完整降低并发数、增加随机等待、补 Referer 和 User-Agent某些层级全是灰块或黑块该图层在这个层级没有数据或服务端临时故障切换图层子域、检查该层级是否存在、换时间再试拼图后位置偏移、错位y 坐标翻转错误或边界瓦片未外扩检查 XYZ/TMS 规则、外扩 1 到 2 张瓦片文件存在但打不开下载进程被强杀导致 0 字节文件判断文件大小大于 0重下缺失瓦片个别瓦片永远下载失败服务端数据缺失或单瓦片损坏单独记录到 missing.txt拼图时填充这张表是排查的第一站。遇到问题先对号入座不要一上来就怀疑代码写错了90% 的下载问题出在参数配置和请求行为上。5.2 三条典型踩坑记录现象、原因与解决踩坑一并发 16 跑 2000 张后开始大量 403现象前 500 张一切正常之后 403 出现的频率越来越高最终几乎全部失败。原因服务端对单 IP 的请求速率有限制16 个线程同时请求每秒钟请求数稳定超过阈值被限流了。解决把 workers 降到 6wait_range 改为 0.3 到 0.8 秒同时补上 Referer 请求头让请求看起来更接近浏览器行为。重试时用指数退避而不是立刻重试等限流窗口过去。踩坑二单张瓦片都正常拼出来整张图南北颠倒现象下载单张瓦片看内容没问题但按目录拼成大图后整个区域上下反转。原因这个瓦片服务用的是 TMS 规则y 从底部开始数而我按 XYZ 的 y 从顶部开始计算任务编号等于把 y 方向整个镜像了。解决在配置里加一个 flip_y 开关计算任务编号后对 y 做一次翻转。这里有个排查技巧先下载一张已知位置的瓦片比如北纬 39.9 度、东经 116.4 度附近看一下和地图客户端显示的位置是否一致不一致就说明方向有问题。踩坑三断点续传后大片瓦片黑块现象进程被强杀后重启代码判断“文件存在”就跳过结果大片瓦片是 0 字节文件拼图时全是黑块。原因下载到一半进程被杀文件只创建了没写入数据大小是 0。而判断逻辑只查存在性没查文件大小。解决download_one 里加上 os.path.getsize(path) 0 的条件0 字节文件视为未下载重跑时会自动覆盖。后续可以在全量任务结束后跑一条清理命令把 0 字节文件删除避免影响拼图工具的判断。6. 下载完成后的体检文件统计、十字抽检与低层级拼图验证下载完成不等于工作完成。几万张瓦片落盘后第一件事是对整个目录做体检而不是直接进拼图流程。每分钟花在体检上的时间能在后面拼图和调试中省回来。6.1 用文件系统命令给瓦片目录“体检”# 统计瓦片总数应该和任务数一致 find tiles -name *.png | wc -l # 找出所有 0 字节文件这些是下载失败的残留 find tiles -name *.png -size 0 | head -20 # 查看目录总大小和预估磁盘占用对比 du -sh tiles逻辑说明第一条命令核对数量数量对不上说明有任务丢失。第二条命令找出 0 字节文件这一步必须做因为前面踩过坑文件存在不代表内容完整。第三条命令看磁盘占用如果 z15 层级的瓦片数量异常多通常说明边界范围算大了任务数比预期翻了倍。补充一条不同层级瓦片数量符合 4 倍关系。比如 z10 有 121 张z11 应该约 484 张。如果某个层级数量突然不符合这个规律那一层的范围换算多半有问题。这条规则能快速定位是哪个层级出错。6.2 低层级拼图抽检一眼看出南北颠倒体检通过后用低层级瓦片拼一张全局轮廓图。低层级瓦片数量少z3 或 z4 全世界的瓦片也就几十张人工核对成本极低但能暴露几乎所有方向性问题。抽检方法取任务范围的中心点在 z3、z5、z8 三个层级各下载一圈瓦片用图片查看工具打开看轮廓。重点看两点一是地物形状是否正确河流、海岸线的走向有没有镜像二是边缘是否完整有没有裁切痕迹。方向错误在低层级图上一眼就能看出来但在单张瓦片和高层级图上是完全无感的。有一次我下载了九千多张瓦片单张检查没有任何问题拼出来才发现整张图上下颠倒原因是 y 方向处理错了。那张低层级预览图让我一眼看出河流走向反了而检查单张瓦片根本发现不了。从那以后我的习惯是任何批量下载完成后先拼低层级全局轮廓图确认方向再做拼接和裁剪这个习惯帮我避开了至少三次同样的翻车。希望帮到你。本文还有配套的精品资源点击获取
简介地图瓦片下载工具AZMap 4.9是一款专业的地图数据获取软件基于Web GIS的瓦片分割技术帮助用户从Google Maps、Bing Maps、OpenStreetMap等在线服务高效下载任意区域、多个层级的地图瓦片。它适用于需要离线地图的户外探险、GIS空间分析、地图制图、网络地图服务备份以及地图应用开发等场景尤其方便网络条件有限时的数据获取。压缩包内共841个文件主要包含JavaScript脚本、投影定义文件prj、PNG格式瓦片图片、DLL动态库、CSV地理数据以及必要的运行配置压缩后总大小约47.15MB整体结构清晰便于按需提取使用。该工具核心程序为AZMap.exe版本4.9同时配有任务索引文件azdb、地区地理数据库如河北数据以及多个批处理脚本如初始化IIS、创建/删除服务器等用户可直接运行程序通过界面设置地图源、层级范围、坐标系统和输出格式也可参考内置脚本和配置文件进行二次定制。目前已有1210人学习下载是地理信息相关从业者和爱好者获取瓦片数据、搭建离线地图服务的实用工具。1. 地图瓦片下载工具到底在解决什么为什么截图拼图不是选项地图瓦片下载工具简单说就是把在线地图按“层级-横-纵”的网格编号规则批量抓取小方块图片到本地。很多人第一反应是截图真正做离线底图的人不会这么干截图没有坐标信息拼接后无法对齐更没法按缩放级别切换。这个工具解决的问题是给定一个矩形范围自动算出覆盖这个范围所有层级的瓦片编号并发下载、断点续传、失败重试最后得到一套能在本地直接使用的瓦片目录。适用人群很明确GIS 开发、需要离线底图的业务系统、以及做数据预处理的技术人员。它的核心不是“爬虫”而是坐标系换算和并发调度这两件事做明白工具就算立住了。2. 先搞懂瓦片编号与坐标系z/x/y 背后的 Web Mercator 换算下载工具的输入是经纬度范围输出是一堆编号。如果不懂编号规则下载器在你眼里就是个黑匣子参数填错、y 方向反了、层级算多了全要等跑完才发现。所以先花一章把编号规则和换算逻辑讲透后面写代码才有把握。2.1 XYZ 编号规则为什么一张地图会被切成 2^z 个小方块在线地图把世界地图切成无数个 256x256 的小图片每一张叫一张瓦片。z 代表缩放层级z0 时整个世界地图是一张 256x256 的图z1 时切成 2x2 共 4 张z2 时是 4x4 共 16 张。规律是层级为 z 时地图被切成 2^z 行、2^z 列。x 表示从左往右数的列号y 表示从上往下数的行号这就是最常见的 XYZ 规则绝大多数在线瓦片服务都遵循它。这套规则背后是 Web Mercator 投影。它把地球按经纬度网格投影成一个正方形平面纬度范围大约在正负 85.05 度之间超出这个范围的地图会被切掉。为什么下载工具必须知道它因为把经纬度换算成瓦片行列号时纬度方向用的是反双曲正弦函数不是简单的线性除法。很多初版工具在这里翻车直接拿经纬度除以 360 再乘 2^z低纬度区域看着没问题高纬度地区就越偏越远。还要注意一个隐藏规则XYZ 的 y 从顶部开始数而另一种叫 TMS 的规则是 y 从底部开始数。同一个经纬度点在两种规则下算出的 y 编号完全相反。下载工具里通常有个“翻转 Y”开关选错了拼出来就是上下颠倒。判断方法很简单下载一张已知位置的瓦片比如北纬 39.9 度、东经 116.4 度附近的一个点看看显示内容对不对再做全量下载。2.2 经纬度换算成瓦片行列号一个不需要 GIS 依赖的 Python 函数先用纯标准库写一个换算函数不依赖任何 GIS 库这样在任何 Python 环境里都能跑也方便理解公式本身。import math def lonlat_to_tile(lon, lat, zoom): # Web Mercator 有效纬度范围约是正负 85.05 度 lat max(-85.05, min(85.05, lat)) n 2 ** zoom # x 方向是线性映射经度 -180~180 映射到 0~2^z x (lon 180.0) / 360.0 * n # y 方向用 Web Mercator 投影公式asinh(tan(lat_rad)) lat_rad math.radians(lat) y (1.0 - math.asinh(math.tan(lat_rad)) / math.pi) / 2.0 * n return int(x), int(y) def calc_tile_range(west, south, east, north, zoom): # 西南角算出的是 x 最小、y 最大东北角算出的是 x 最大、y 最小 x_min, y_max lonlat_to_tile(west, south, zoom) x_max, y_min lonlat_to_tile(east, north, zoom) # 因为 y 从顶部开始数纬度越高 y 越小这里必须交换一次 if y_min y_max: y_min, y_max y_max, y_min return x_min, x_max, y_min, y_max逻辑说明lonlat_to_tile 先限制纬度范围避免投影公式在极区算出无效值。x 方向是线性映射经度从 -180 到 180 对应 x 从 0 到 2^z。y 方向是标准的 Web Mercator 逆变换公式里用了 asinh 而不是 log 加 cos 的写法两种写法数学上等价asinh 在数值上更稳定也不容易出现除零。参数说明west、south 是范围西南角的经纬度east、north 是东北角的经纬度。calc_tile_range 返回的 x_min、x_max、y_min、y_max 已经按 XYZ 规则整理好可以直接用来生成下载任务。这里有个容易忽略的点计算结果是“覆盖范围”而不是“完整落在范围内”的瓦片集合边缘瓦片只覆盖到边界的一部分。所以实际下载时我会把范围外扩 1 到 2 张瓦片宁愿多下一点也不要拼图时发现边缘缺一条。这个习惯后面拼图时会解释原因。3. Python 实现最小可用版从串行下载到并发提速的完整代码原理讲完开始写能跑的东西。我用 Python 标准库实现不引入任何第三方依赖下载逻辑用 urllib.request。先把单线程版本跑通再改造成线程池并发这样新手能看清楚每一步在干什么熟手也能直接拿代码当模板改。3.1 串行版本30 行代码把指定范围瓦片落盘先写一个下载单张瓦片的函数顺便解决掉“重复下载”和“目录结构”两个基础问题。import os import urllib.request TILE_URL https://tiles.example.com/{z}/{x}/{y}.png HEADERS {User-Agent: Mozilla/5.0 (study script)} OUTPUT_DIR tiles def download_one(z, x, y): path f{OUTPUT_DIR}/{z}/{x}/{y}.png # 已存在且文件非空视为已下载直接跳过 if os.path.exists(path) and os.path.getsize(path) 0: return True os.makedirs(os.path.dirname(path), exist_okTrue) url TILE_URL.format(zz, xx, yy) req urllib.request.Request(url, headersHEADERS) # timeout 设 15 秒防止个别瓦片卡死整个任务 with urllib.request.urlopen(req, timeout15) as resp, open(path, wb) as f: f.write(resp.read()) return True逻辑说明下载前先检查文件是否存在并且大于 0 字节这是最简单的断点续传。很多工具只判断“文件存在”就跳过结果进程被强杀后留下一堆 0 字节文件重跑时全部跳过拼图才发现缺片。判断非空这个习惯建议直接刻进肌肉记忆。目录结构按 z/x/y.png 组织和 URL 路径保持一致之后做本地瓦片服务时可以直接把目录丢给静态服务器。参数说明TILE_URL 里的 {z}/{x}/{y} 是占位符format 会依次替换。HEADERS 里的 User-Agent 必须带有些瓦片服务对没有 UA 的请求直接返回 403。timeout 15 秒是保守值内网瓦片服务可以降到 5 秒公网服务建议保持 15 秒以上。串行调用很简单def main(): # 示例z10x 从 300 到 310y 从 400 到 410 for z in [10]: for x in range(300, 311): for y in range(400, 411): download_one(z, x, y) print(fz{z} done) if __name__ __main__: main()这个版本能跑但速度很慢。121 张瓦片如果每张耗时 0.3 秒串行要接近 40 秒。真实项目通常要下几万张串行得跑到天荒地老。下一步改成并发。3.2 并发版本线程数、超时与重试的推荐参数瓦片下载是典型的 IO 密集型任务瓶颈在网络等待不在 CPU。Python 的多线程在这里正好合适直接上 ThreadPoolExecutor代码改动量很小。import time import random from concurrent.futures import ThreadPoolExecutor, as_completed def download_one_with_retry(z, x, y, max_retry3): for attempt in range(max_retry): try: # 每张瓦片下载前随机等待 0.1~0.3 秒降低请求特征 time.sleep(random.uniform(0.1, 0.3)) download_one(z, x, y) return True except Exception as e: # 指数退避第 1 次失败等 1 秒第 2 次等 2 秒第 3 次等 4 秒 wait 2 ** attempt print(f[retry] z{z} x{x} y{y}, attempt{attempt 1}, wait{wait}s, err{e}) time.sleep(wait) return False def download_many(tasks, workers8): failed [] with ThreadPoolExecutor(max_workersworkers) as pool: future_map { pool.submit(download_one_with_retry, z, x, y): (z, x, y) for z, x, y in tasks } for fut in as_completed(future_map): z, x, y future_map[fut] if not fut.result(): failed.append((z, x, y)) return failed逻辑说明download_many 把任务列表全部提交给线程池as_completed 遍历结果失败的记录到 failed 列表。download_one_with_retry 在原有下载逻辑外包了一层重试每次失败后等待时间按 2 的幂次增长1 秒、2 秒、4 秒避免失败后立刻重试导致的服务端压力叠加。参数说明max_workers8 是保守起点。太慢浪费带宽太快容易被服务端限流甚至封 IP8 是多数公网瓦片服务能接受的并发数。如果你访问的是内网自建瓦片服务可以调到 16 或 32如果是公网商业服务建议从 4 试起。random.uniform(0.1, 0.3) 这行是经验之谈固定间隔的请求很容易被识别成脚本加一点随机抖动能把触发限流的概率降一个量级。并发版本跑完后把 failed 列表打印出来看看。如果失败率超过 1%先别急着全量下载多半是并发太高或者请求头不全先小范围试 200 张摸清服务端的脾气再铺开。这一步能省下大量重跑时间。4. 工程化必做的三件事失败重试、频率控制与断点续传单机和并发的代码能跑通但离“工具”还差得远。真实下载任务动辄几万张瓦片跑几个小时中途网络抖动、服务端限流、进程被杀都会发生。这章把配置管理、频率控制和失败恢复三件事补齐工具才算有工程化的样子。4.1 用配置对象统一范围、层级与并发参数参数散落在代码里没法维护。我把所有可调项收敛到一个配置对象里命令行也好、配置文件也好最终都转成这个对象传给下载逻辑。from dataclasses import dataclass dataclass class DownloadConfig: west: float 116.0 # 范围西边经度 south: float 39.0 # 范围南边纬度 east: float 117.0 # 范围东边经度 north: float 40.0 # 范围北边纬度 min_zoom: int 5 # 最小层级 max_zoom: int 15 # 最大层级 workers: int 8 # 并发线程数 timeout: int 15 # 单张瓦片超时秒数 max_retry: int 3 # 最大重试次数 output_dir: str tiles # 输出目录 wait_range: tuple (0.1, 0.3) # 随机等待区间 def generate_tasks(cfg): tasks [] for z in range(cfg.min_zoom, cfg.max_zoom 1): x_min, x_max, y_min, y_max calc_tile_range( cfg.west, cfg.south, cfg.east, cfg.north, z) # 外扩 1 张瓦片边缘才不会被裁掉 x_min max(0, x_min - 1) x_max min(2 ** z - 1, x_max 1) y_min max(0, y_min - 1) y_max min(2 ** z - 1, y_max 1) for x in range(x_min, x_max 1): for y in range(y_min, y_max 1): tasks.append((z, x, y)) return tasks逻辑说明generate_tasks 把经纬度范围按每个层级分别换算成任务列表。外扩一张瓦片那两行是踩坑踩出来的不扩的边缘瓦片在拼接时往往缺一条边。x_max 和 y_max 的上限是 2^z - 1因为编号从 0 开始超过这个值就超出世界地图范围了。参数建议min_zoom 到 max_zoom 跨度越大任务量增长越快。层级每加 1瓦片数量是上一层的 4 倍。z15 覆盖一个普通地级市范围大约要几万张z18 就是几百万张级别磁盘空间和下载时长要提前算清楚。4.2 失败重试与频率控制别让单 IP 触发限流网络请求的失败是常态不是意外。我一般把频率控制和重试逻辑封装在一起这样调用方不需要关心细节。import time import random class TileDownloader: def __init__(self, cfg: DownloadConfig): self.cfg cfg self.failed [] def download_one(self, z, x, y): path f{self.cfg.output_dir}/{z}/{x}/{y}.png if os.path.exists(path) and os.path.getsize(path) 0: return True os.makedirs(os.path.dirname(path), exist_okTrue) url TILE_URL.format(zz, xx, yy) req urllib.request.Request(url, headersHEADERS) wait random.uniform(*self.cfg.wait_range) time.sleep(wait) with urllib.request.urlopen(req, timeoutself.cfg.timeout) as resp, open(path, wb) as f: f.write(resp.read()) return True def run(self, tasks): with ThreadPoolExecutor(max_workersself.cfg.workers) as pool: future_map { pool.submit(self._with_retry, z, x, y): (z, x, y) for z, x, y in tasks } for fut in as_completed(future_map): z, x, y future_map[fut] if not fut.result(): self.failed.append((z, x, y)) return self.failed def _with_retry(self, z, x, y): for attempt in range(self.cfg.max_retry): try: return self.download_one(z, x, y) except Exception as e: wait 2 ** attempt print(f[retry] z{z} x{x} y{y}, attempt{attempt 1}, wait{wait}s) time.sleep(wait) return False逻辑说明把重试和下载拆成两个方法_with_retry 只负责重试策略download_one 只负责单张下载职责清楚。随机等待放在下载前而不是放在重试前这样整个任务流的请求间隔天然就是抖动的不会出现整批线程同时请求再同时休眠的脉冲式流量。参数说明wait_range 默认 0.1 到 0.3 秒对应单线程每秒钟约 3 到 10 张。8 个线程时整体速度大约每秒 30 到 50 张这个速度对大多数公网服务是安全的。如果遇到严格限流的服务端把 workers 降到 4、wait_range 调到 0.3 到 0.6大多数 403 问题都能缓解。4.3 断点续传把 failed.csv 当成后悔药跑了几十分钟突然断网任务失败记录得留下来不然重跑又是几十分钟。我习惯把失败任务写进 CSV下次启动时先读这个文件。def write_failed(failed, pathfailed.csv): with open(path, w) as f: for z, x, y in failed: f.write(f{z},{x},{y}\n) def load_failed(pathfailed.csv): tasks [] if os.path.exists(path): with open(path) as f: for line in f: line line.strip() if not line: continue z, x, y map(int, line.split(,)) tasks.append((z, x, y)) return tasks逻辑说明write_failed 把失败的三元组按行写入 CSVload_failed 在下次启动时读回来重新丢进线程池。这个文件就是你的后悔药。配合 download_one 里的“存在且非空就跳过”逻辑重跑只补缺失的瓦片不会重复下载已完成的部分。使用建议跑完一次全量任务后把 failed.csv 加载进来单独重试两三轮直到列表为空。如果某几张瓦片反复失败多半是服务端本身缺图不是网络问题直接记录到 missing.txt 里拼图时做特殊处理。断点续传的粒度到单张瓦片就足够了不需要做到字节级断点那对图片下载毫无意义。5. 瓦片下载的常见问题与排查403、黑块、坐标偏移与零字节这章把我在实际下载中遇到最多的问题集中列出来按“现象、原因、解决”的格式写。这些问题单看都像玄学其实背后的原因非常固定排查顺序也有规律可循。5.1 先看现象对照表5 类最常翻车的问题现象可能原因解决方向下载到一半开始大量 403请求频率太高或请求头不完整降低并发数、增加随机等待、补 Referer 和 User-Agent某些层级全是灰块或黑块该图层在这个层级没有数据或服务端临时故障切换图层子域、检查该层级是否存在、换时间再试拼图后位置偏移、错位y 坐标翻转错误或边界瓦片未外扩检查 XYZ/TMS 规则、外扩 1 到 2 张瓦片文件存在但打不开下载进程被强杀导致 0 字节文件判断文件大小大于 0重下缺失瓦片个别瓦片永远下载失败服务端数据缺失或单瓦片损坏单独记录到 missing.txt拼图时填充这张表是排查的第一站。遇到问题先对号入座不要一上来就怀疑代码写错了90% 的下载问题出在参数配置和请求行为上。5.2 三条典型踩坑记录现象、原因与解决踩坑一并发 16 跑 2000 张后开始大量 403现象前 500 张一切正常之后 403 出现的频率越来越高最终几乎全部失败。原因服务端对单 IP 的请求速率有限制16 个线程同时请求每秒钟请求数稳定超过阈值被限流了。解决把 workers 降到 6wait_range 改为 0.3 到 0.8 秒同时补上 Referer 请求头让请求看起来更接近浏览器行为。重试时用指数退避而不是立刻重试等限流窗口过去。踩坑二单张瓦片都正常拼出来整张图南北颠倒现象下载单张瓦片看内容没问题但按目录拼成大图后整个区域上下反转。原因这个瓦片服务用的是 TMS 规则y 从底部开始数而我按 XYZ 的 y 从顶部开始计算任务编号等于把 y 方向整个镜像了。解决在配置里加一个 flip_y 开关计算任务编号后对 y 做一次翻转。这里有个排查技巧先下载一张已知位置的瓦片比如北纬 39.9 度、东经 116.4 度附近看一下和地图客户端显示的位置是否一致不一致就说明方向有问题。踩坑三断点续传后大片瓦片黑块现象进程被强杀后重启代码判断“文件存在”就跳过结果大片瓦片是 0 字节文件拼图时全是黑块。原因下载到一半进程被杀文件只创建了没写入数据大小是 0。而判断逻辑只查存在性没查文件大小。解决download_one 里加上 os.path.getsize(path) 0 的条件0 字节文件视为未下载重跑时会自动覆盖。后续可以在全量任务结束后跑一条清理命令把 0 字节文件删除避免影响拼图工具的判断。6. 下载完成后的体检文件统计、十字抽检与低层级拼图验证下载完成不等于工作完成。几万张瓦片落盘后第一件事是对整个目录做体检而不是直接进拼图流程。每分钟花在体检上的时间能在后面拼图和调试中省回来。6.1 用文件系统命令给瓦片目录“体检”# 统计瓦片总数应该和任务数一致 find tiles -name *.png | wc -l # 找出所有 0 字节文件这些是下载失败的残留 find tiles -name *.png -size 0 | head -20 # 查看目录总大小和预估磁盘占用对比 du -sh tiles逻辑说明第一条命令核对数量数量对不上说明有任务丢失。第二条命令找出 0 字节文件这一步必须做因为前面踩过坑文件存在不代表内容完整。第三条命令看磁盘占用如果 z15 层级的瓦片数量异常多通常说明边界范围算大了任务数比预期翻了倍。补充一条不同层级瓦片数量符合 4 倍关系。比如 z10 有 121 张z11 应该约 484 张。如果某个层级数量突然不符合这个规律那一层的范围换算多半有问题。这条规则能快速定位是哪个层级出错。6.2 低层级拼图抽检一眼看出南北颠倒体检通过后用低层级瓦片拼一张全局轮廓图。低层级瓦片数量少z3 或 z4 全世界的瓦片也就几十张人工核对成本极低但能暴露几乎所有方向性问题。抽检方法取任务范围的中心点在 z3、z5、z8 三个层级各下载一圈瓦片用图片查看工具打开看轮廓。重点看两点一是地物形状是否正确河流、海岸线的走向有没有镜像二是边缘是否完整有没有裁切痕迹。方向错误在低层级图上一眼就能看出来但在单张瓦片和高层级图上是完全无感的。有一次我下载了九千多张瓦片单张检查没有任何问题拼出来才发现整张图上下颠倒原因是 y 方向处理错了。那张低层级预览图让我一眼看出河流走向反了而检查单张瓦片根本发现不了。从那以后我的习惯是任何批量下载完成后先拼低层级全局轮廓图确认方向再做拼接和裁剪这个习惯帮我避开了至少三次同样的翻车。希望帮到你。本文还有配套的精品资源点击获取
