离线GIS底图构建：瓦片下载、BD-09坐标转换与MBTiles打包

1. 项目背景与核心需求拆解

离线GIS底图构建与BD-09坐标转换，是我最近在模拟项目X里反复打磨的一条链路。瓦片下载工具看起来只是循环拼URL，但真正落地时，坐标偏几十米、层级算错、断点续传写出空文件、拼接后接缝错位，任何一个都能让底图不可用。这篇不聊空泛概念，直接把一套可复现的方案拆开：从瓦片金字塔和任务范围计算，到并发下载、限速重试、断点续传，再到BD-09坐标转换、MBTiles打包和GIS软件加载。适合做内网演示、外业离线地图、数据大屏底图缓存的朋友；新手可以照着搭，老手重点看坐标转换和排查表。

1.1 谁需要离线GIS底图

先说清楚适用人群。第一类是内网演示环境，很多演示机房没有外网，或者网络策略限制严格，在线底图加载不稳定，这时候把某一区域的瓦片提前缓存下来，演示时本地服务直接出图，心里踏实。第二类是外业离线场景，比如巡检、测绘辅助、现场记录，设备在野外没有稳定网络，底图必须提前准备好，而且最好能按项目范围裁剪，别把整座城市都塞进平板。第三类是数据大屏和固定看板，底图变化频率低，完全可以把瓦片固化成本地资源，减少运行时对外部服务的依赖。第四类是教学和复现实验，需要一套可控的底图环境，方便学生理解瓦片金字塔、坐标体系和地图加载之间的关系。

这些场景的共同点不是“想把地图搬回家”，而是“在受限环境里稳定展示自己有权使用的底图”。所以工具的目标很明确：按边界范围生成任务、按层级下载瓦片、按坐标体系做转换、按标准格式打包、按本地服务加载。它不追求大而全，追求的是可重复、可检查、可维护。你拿到的不是一张神秘大图，而是一套目录清晰、元数据完整、缺片能查的瓦片资产。

1.2 瓦片下载工具的核心需求

第一项需求是范围可控。给定一个经纬度矩形和缩放级别区间，工具要能算出需要下载的瓦片行列号范围，而不是盲目从0到最大层级全量抓取。第二项需求是断点续传。下载几千张瓦片时，网络抖动、进程中断、磁盘写满都很常见，重新全量下载既浪费时间也增加请求压力。第三项需求是失败可查。哪些瓦片404、哪些超时、哪些返回空内容，必须落到日志里，不能只打印一个“完成”。第四项需求是坐标可转。业务数据可能是BD-09坐标，底图瓦片可能按另一种投影规则组织，两者不统一，叠加就会偏移。第五项需求是产物标准。下载完的目录要能直接被本地服务读取，也要能打包成MBTiles，方便桌面GIS软件或移动端加载。

这里我特别想强调“不要绕过鉴权”。工具只处理公开可访问的瓦片，或者你已经获得授权的接口。不要在代码里塞登录态、不要伪造身份、不要做高频轰炸。下载器不是爬虫武器，它是底图资产整理工具。把并发控制在合理范围，加上重试间隔和限速，既是对服务方的基本尊重，也能避免自己的任务被封禁。很多新手一上来开64线程，结果一半请求失败，还以为是代码写错了，其实就是节奏太猛。

1.3 影响范围：从内网演示到外业离线

这套链路的影响范围比想象中大。最直接的是数据准备效率：手工点选下载几乎不可维护，脚本化以后，一个区域的任务清单可以版本化保存，下次换范围只改配置。其次是底图一致性：同一套瓦片目录配同一份元数据，演示机、笔记本、平板看到的是同一张底图，不会出现“这台机器能加载、那台机器白屏”的尴尬。第三是坐标精度：BD-09转换如果做错，业务点会整体偏移，短距离看像“点位不准”，长距离看像“数据错了”，排查成本很高。第四是存储成本：层级每加一级，瓦片数量大约乘四，不估算就下载，很容易把磁盘写满。

我一般会把影响范围拆成三层来看。展示层关心加载速度和清晰度，决定最小层级和最大层级；数据层关心坐标基准和边界范围，决定转换链和裁剪框；运维层关心缓存目录、日志、打包产物和更新策略。三层想清楚，工具才不会变成一次性脚本。下面这张表是我在模拟项目X里常用的范围评估思路，数值只是示例，实际按你的区域大小和清晰度要求调整。

2. 整体方案设计与技术选型

2.1 为什么用瓦片金字塔而不是一张大图

地图底图最忌讳“一张大图打天下”。一张覆盖整个区域的超大图片，文件体积大、内存占用高、缩放时要么模糊要么卡顿，局部更新还得整张重做。瓦片金字塔的思路是把地图按层级切成固定大小的小图片，常见是256×256像素，每一级覆盖同样的地理范围，但行列数翻倍。层级z=0通常是一张瓦片，z=1是2×2，z=2是4×4，依次类推。前端或GIS软件根据当前视野和缩放级别，只请求需要的几张瓦片，加载快，缓存也方便。

生活里可以把它想成快递分拣。你不会把整个仓库的货一次性倒在地上找，而是按区域、货架、格子一层层定位。瓦片就是地图的“货架格子”，z是仓库层级，x是横向货架，y是纵向货架。离线底图要做的，就是把你关心的那几层格子提前放进本地仓库。这样做还有一个好处：缺片很容易发现。哪一层、哪一行、哪一列缺了，目录里一眼就能看出来，补下载也只需要补那几张。

2.2 下载器架构：并发、断点、限速

下载器我建议分成四块：任务生成、下载执行、状态记录、产物整理。任务生成负责把经纬度范围转成瓦片行列号；下载执行负责并发请求和重试；状态记录负责记录成功、跳过、404、失败；产物整理负责目录规范、打包和校验。并发不是为了炫技，而是为了在合理时间内完成几千张瓦片的下载。但并发数要克制，我一般从4到8开始试，观察失败率和响应时间，再决定是否调整。断点续传的核心不是复杂的数据库，而是“文件存在且大小大于0就跳过”，写文件时先写临时文件，成功后再重命名，避免中断留下半张图。

下面是一段简化但可用的Python下载器骨架，重点是断点、重试和临时文件。实际使用时把瓦片地址换成你有权访问的接口，不要塞任何鉴权绕过逻辑。

import os import time import requests from concurrent.futures import ThreadPoolExecutor, as_completed TILE_URL = "https://tile.example.com/{z}/{x}/{y}.png" OUT_DIR = "tiles" HEADERS = {"User-Agent": "OfflineTileTool/1.0"} def tile_path(z, x, y): return os.path.join(OUT_DIR, str(z), str(x), f"{y}.png") def download_one(z, x, y, retries=3, timeout=10): path = tile_path(z, x, y) if os.path.exists(path) and os.path.getsize(path) > 0: return "skip" os.makedirs(os.path.dirname(path), exist_ok=True) url = TILE_URL.format(z=z, x=x, y=y) for i in range(retries): try: r = requests.get(url, headers=HEADERS, timeout=timeout) if r.status_code == 200 and r.content and len(r.content) > 100: tmp = path + ".tmp" with open(tmp, "wb") as f: f.write(r.content) os.replace(tmp, path) return "ok" if r.status_code == 404: return "404" time.sleep(0.5 * (i + 1)) except Exception: time.sleep(0.5 * (i + 1)) return "fail" def run_tasks(tasks, workers=6): stats = {"ok": 0, "skip": 0, "404": 0, "fail": 0} with ThreadPoolExecutor(max_workers=workers) as pool: futures = [pool.submit(download_one, z, x, y) for z, x, y in tasks] for f in as_completed(futures): stats[f.result()] += 1 time.sleep(0.02) return stats

这段代码有两个细节值得说。第一，len(r.content) > 100是防止有些服务返回一张极小的占位图或者错误页，直接当成功存下来，后面拼接会出现空白块。第二，os.replace在同一磁盘内是原子操作，比直接写目标文件安全。并发部分我加了很小的sleep，不是必须，但能削一下瞬时峰值。真实项目里最好把失败任务写成CSV或JSONL，包含z、x、y、状态码、时间，方便二次补抓。

2.3 坐标体系选择与转换链

坐标体系是离线底图最容易踩坑的地方。WGS84是通用地理坐标基准，GPS设备、很多公开数据都围绕它；GCJ02是在WGS84基础上做偏移的坐标体系，部分在线地图使用；BD09又是在GCJ02基础上再做一次偏移的坐标体系，常见于某些平台的展示坐标。三者不能混着用，混用就会出现整体偏移。业务数据如果是BD09，而底图瓦片编号按WGS84或GCJ02计算，你直接叠加，点位就会偏。正确做法是先明确每一层数据到底是什么坐标，再做转换链。

我通常把WGS84当作“中间语言”。BD09转WGS84不是简单减一个固定值，而是先做BD09到GCJ02，再做GCJ02到WGS84。GCJ02到WGS84也没有完美的解析逆函数，工程上用迭代逼近，三十次以内基本够用。这里要提醒一句：转换精度再高，也不能弥补“源头坐标标错”的问题。你拿到的业务点如果本身是BD09，就不要先转WGS84再当BD09用，链路一乱，后面全是玄学偏移。

3. 核心细节解析与实操要点

3.1 瓦片编号计算与层级选择

瓦片编号的核心是把经纬度映射到当前层级的行列号。常见Web Mercator瓦片规则下，经度从-180到180线性映射到0到2^z-1，纬度通过墨卡托投影映射。公式不复杂，但纬度方向容易搞反：y通常从上往下增大，所以左上角是较小的x和较小的y，右下角是较大的x和较大的y。你拿边界范围生成任务时，要用“左上角”和“右下角”两个点分别算，不能把最小纬度直接当左上。

import math def lonlat_to_tile(lon, lat, z): n = 2 ** z x = int((lon + 180.0) / 360.0 * n) lat_rad = math.radians(lat) y = int((1.0 - math.log(math.tan(lat_rad) + 1.0 / math.cos(lat_rad)) / math.pi) / 2.0 * n) return x, y def tile_range(min_lon, min_lat, max_lon, max_lat, z): x1, y1 = lonlat_to_tile(min_lon, max_lat, z) x2, y2 = lonlat_to_tile(max_lon, min_lat, z) return x1, y1, x2, y2

层级选择要看用途，不要盲目追高。z=10到z=12适合区域概览，z=13到z=15适合城区演示，z=16以上适合街道级细看。每加一级，行列数大约翻倍，瓦片总数大约乘四。你可以先算数量再决定：数量 = (x2-x1+1) * (y2-y1+1)，再乘平均瓦片大小。假设平均每张15KB，一个范围有8000张，就是约120MB；如果z再加两级，可能直接到2GB。这个估算不精确，但足够让你在下载前冷静一下。

注意：瓦片编号规则依赖平台和投影，不要拿一套公式硬套所有服务。先用几个已知点验证行列号，再批量跑。

3.2 BD-09坐标转换原理与代码实现

BD09转换的代码网上一搜一大把，但很多人只抄了正算，没写逆算，或者逆算直接用线性减法，结果精度不够。我的建议是把转换链写清楚：WGS84到GCJ02用正算，GCJ02到BD09用偏移公式，BD09回GCJ02用逆偏移，GCJ02回WGS84用迭代逼近。下面这份代码是工程里常用的简化实现，去掉了范围判断，实际项目可以按业务边界做裁剪。

import math A = 6378245.0 EE = 0.00669342162296594323 X_PI = math.pi * 3000.0 / 180.0 def _transform_lat(x, y): ret = -100.0 + 2.0 * x + 3.0 * y + 0.2 * y * y + 0.1 * x * y + 0.2 * math.sqrt(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.0 * math.sin(y * math.pi / 30.0)) * 2.0 / 3.0 return ret def _transform_lon(x, y): ret = 300.0 + x + 2.0 * y + 0.1 * x * x + 0.1 * x * y + 0.1 * math.sqrt(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 def wgs84_to_gcj02(lon, lat): dlat = _transform_lat(lon - 105.0, lat - 35.0) dlon = _transform_lon(lon - 105.0, lat - 35.0) radlat = lat / 180.0 * math.pi magic = math.sin(radlat) magic = 1 - EE * magic * magic sqrtmagic = math.sqrt(magic) dlat = (dlat * 180.0) / ((A * (1 - EE)) / (magic * sqrtmagic) * math.pi) dlon = (dlon * 180.0) / (A / sqrtmagic * math.cos(radlat) * math.pi) return lon + dlon, lat + dlat def gcj02_to_bd09(lon, lat): z = math.sqrt(lon * lon + lat * lat) + 0.00002 * math.sin(lat * X_PI) theta = math.atan2(lat, lon) + 0.000003 * math.cos(lon * X_PI) return z * math.cos(theta) + 0.0065, z * math.sin(theta) + 0.006 def bd09_to_gcj02(lon, lat): x = lon - 0.0065 y = lat - 0.006 z = math.sqrt(x * x + y * y) - 0.00002 * math.sin(y * X_PI) theta = math.atan2(y, x) - 0.000003 * math.cos(x * X_PI) return z * math.cos(theta), z * math.sin(theta) def gcj02_to_wgs84(lon, lat): wgs_lon, wgs_lat = lon, lat for _ in range(30): gcj_lon, gcj_lat = wgs84_to_gcj02(wgs_lon, wgs_lat) d_lon = gcj_lon - lon d_lat = gcj_lat - lat if abs(d_lon) < 1e-9 and abs(d_lat) < 1e-9: break wgs_lon -= d_lon wgs_lat -= d_lat return wgs_lon, wgs_lat def bd09_to_wgs84(lon, lat): gcj_lon, gcj_lat = bd09_to_gcj02(lon, lat) return gcj02_to_wgs84(gcj_lon, gcj_lat)

这段代码里，bd09_to_gcj02是逆偏移，gcj02_to_wgs84是迭代反解。实际测下来，三十次迭代对绝大多数业务点足够，耗时也可以接受。如果你要批量转换几十万个点，可以先把结果缓存起来，避免重复计算。还有一点：转换前后一定要用已知点做对照检查。找两三个你确信坐标基准的点，转换成WGS84后放到地图上，看偏移方向是否一致。如果所有点都朝同一个方向偏，通常是坐标体系用错；如果偏移方向杂乱，可能是数据本身有问题。

3.3 下载任务配置与缓存目录

缓存目录我建议按z/x/y.png组织，这是绝大多数本地瓦片服务和打包工具都能识别的结构。目录下再放一个meta.json，记录边界范围、层级区间、坐标体系、生成时间、瓦片地址模板、任务总数。别小看这个元数据，过两周你回来补下载，没有它根本记不清当时用的是哪个范围、哪个层级、哪个坐标基准。日志建议按任务批次分文件，成功、跳过、404、失败分开统计。

{ "name": "simulation-project-x-basemap", "min_zoom": 10, "max_zoom": 15, "bounds": [100.0, 30.0, 100.2, 30.2], "coord_system": "BD09", "tile_url_template": "https://tile.example.com/{z}/{x}/{y}.png", "created_at": "2025-01-01T00:00:00" }

任务生成时，我习惯先把所有z/x/y写成一个清单文件，再交给下载器消费。这样做的好处是可审计：到底要下多少张、哪些层级占大头、失败任务是哪几张，都能从清单里看出来。清单不要太大，几万行以内用JSONL就够；如果上百万行，考虑分片。下载器读取清单时，遇到已存在的非空文件直接跳过，遇到临时文件先删掉再重下，避免半成品干扰。

3.4 拼接与MBTiles打包

拼接大图适合小范围检查和截图，不适合大面积生产。原因很简单：z=15时，100×100张瓦片拼出来就是25600×25600像素，内存很容易爆。我的建议是，日常用MBTiles或目录服务，只有做报告插图时才拼接局部。拼接代码要处理缺片，缺片位置用白色或灰色填充，别让整张图失败。

import os from PIL import Image def mosaic(z, x1, y1, x2, y2, tile_root, out_png): w = (x2 - x1 + 1) * 256 h = (y2 - y1 + 1) * 256 canvas = Image.new("RGB", (w, h), (255, 255, 255)) for x in range(x1, x2 + 1): for y in range(y1, y2 + 1): p = os.path.join(tile_root, str(z), str(x), f"{y}.png") if os.path.exists(p): im = Image.open(p).convert("RGB") canvas.paste(im, ((x - x1) * 256, (y - y1) * 256)) canvas.save(out_png)

MBTiles打包更适合交付。它本质是一个SQLite数据库，里面有metadata和tiles两张表。注意一个关键点：目录里的y是从上往下编号，而MBTiles里的tile_row通常按TMS规则从下往上，所以打包时要翻转：ty = (2 ** z - 1) - y。这个翻转忘了，加载后地图会上下颠倒，很多人第一次打包都会中招。

import os import sqlite3 def pack_mbtiles(out_mbtiles, tile_root, name, min_zoom, max_zoom): if os.path.exists(out_mbtiles): os.remove(out_mbtiles) con = sqlite3.connect(out_mbtiles) con.execute("CREATE TABLE metadata (name TEXT, value TEXT)") con.execute("CREATE TABLE tiles (zoom_level INTEGER, tile_column INTEGER, tile_row INTEGER, tile_data BLOB)") con.execute("CREATE UNIQUE INDEX tile_index ON tiles (zoom_level, tile_column, tile_row)") meta = { "name": name, "format": "png", "minzoom": str(min_zoom), "maxzoom": str(max_zoom), "type": "baselayer" } con.executemany("INSERT INTO metadata VALUES (?,?)", meta.items()) for z in range(min_zoom, max_zoom + 1): zdir = os.path.join(tile_root, str(z)) if not os.path.isdir(zdir): continue for xname in os.listdir(zdir): xdir = os.path.join(zdir, xname) if not os.path.isdir(xdir): continue x = int(xname) for yname in os.listdir(xdir): if not yname.endswith(".png"): continue y = int(yname[:-4]) ty = (2 ** z - 1) - y with open(os.path.join(xdir, yname), "rb") as f: data = f.read() con.execute( "INSERT OR REPLACE INTO tiles VALUES (?,?,?,?)", (z, x, ty, data) ) con.commit() con.close()

打包完别急着交付，先做一次抽检：随机抽几个层级，把MBTiles里的瓦片读出来，和原目录对比大小和内容哈希；再用桌面GIS软件加载，缩放到几个关键点，看是否白屏、是否上下颠倒、是否偏移。这个步骤花不了几分钟，但能省掉后面大量返工。

4. 完整实操过程：从边界范围到可加载底图

4.1 准备边界范围与任务清单

实操第一步是确定边界。不要用“大概这个城市”这种描述，要落到经纬度矩形。比如模拟项目X里，我用一个虚构范围[100.0, 30.0, 100.2, 30.2]做演示，实际项目按你的授权范围和业务需求裁剪。边界确定后，选层级区间，先生成任务清单，统计数量，再决定是否缩范围。这里有个经验：先跑低层级验证链路，再跑高层级。低层级瓦片少，几分钟就能看出坐标、目录、加载是否正常；一上来就跑z=16，失败了很难定位。

def build_tasks(min_lon, min_lat, max_lon, max_lat, min_z, max_z): tasks = [] for z in range(min_z, max_z + 1): x1, y1, x2, y2 = tile_range(min_lon, min_lat, max_lon, max_lat, z) for x in range(x1, x2 + 1): for y in range(y1, y2 + 1): tasks.append((z, x, y)) return tasks tasks = build_tasks(100.0, 30.0, 100.2, 30.2, 10, 15) print(len(tasks))

生成任务后，先看每个层级的数量分布。如果某一级突然暴涨，说明范围跨得太大或者层级选高了。把任务写成JSONL，每行一个[z,x,y]，后面下载器按行读取。清单文件最好和元数据放在一起，形成一个小型资产包：meta.json、tasks.jsonl、tiles/、logs/。这样即使换人接手，也能快速看懂。

4.2 运行下载器与断点续传

运行下载器时，先小并发试跑。比如先取前200个任务，workers=4，观察成功率和响应时间。如果404很多，先检查瓦片地址模板和行列号规则；如果超时多，降低并发或增加超时；如果返回内容很小，检查是不是错误页。试跑通过后再全量跑。全量跑的时候，日志要实时写，别等结束才落盘，否则进程一崩，前面白跑。

python download_tiles.py --tasks tasks.jsonl --workers 6 --timeout 10 --out tiles

断点续传的验证方法很简单：跑到一半按Ctrl+C，再重新运行，看日志里skip数量是否明显增加。如果重新运行又从零开始下载，说明文件存在判断没生效，或者文件写到了临时目录但没重命名。还有一点，磁盘空间要提前看。我一般按估算量的1.5倍预留，因为临时文件、日志、打包产物都会占空间。磁盘写满时，os.replace可能失败，日志里会出现一堆fail，别误判成网络问题。

4.3 本地服务与GIS软件加载

下载完的目录可以直接用本地HTTP服务加载。不要用file://直接打开，很多地图库对本地文件协议限制多，瓦片请求容易失败。起一个简单的静态服务，把tiles/作为根目录，URL模板写成http://127.0.0.1:8000/{z}/{x}/{y}.png。如果你用某开源GIS桌面软件，可以添加一个“XYZ瓦片”图层，填同样的模板；如果你用某前端地图库，配置tileUrl模板即可。加载后先看整体轮廓，再逐级放大，检查接缝和空白。

python -m http.server 8000 --directory tiles

加载时要注意坐标系设置。桌面GIS软件里如果底图图层声明的是WGS84，而你的瓦片实际按另一种坐标基准组织，显示就会偏。最稳妥的方法是先用一个已知点做对照：把同一个业务点分别用BD09和转换后的WGS84加载，看哪个和底图吻合。不要凭感觉“看起来差不多”，偏移几十米在缩放层级低的时候不明显，放大后就会露馅。

4.4 校验与精度检查

校验分三层。第一层是文件层：任务总数、成功数、跳过数、404数、失败数是否对得上，空文件数量是否为0。第二层是图像层：随机抽几个层级，检查瓦片是否能正常打开、尺寸是否256×256、有没有大面积纯色。第三层是坐标层：选三到五个已知点，转换后叠加到底图，量一下偏移方向和距离。下面这张检查表可以照着用。