Last updated: 2026-06-30

Last verified: 2026-06-30 against Joe5027/map-tile-fetcher repository documentation on GitHub, default branch main, commit 24d0b16d02b3bb96b952d694d65e994f455b6bd7.

GitHub repository: Joe5027/map-tile-fetcher

这是一篇学习交流型实战笔记，不是任何地图服务商的官方文档。离线瓦片下载必须只用于你有权访问、下载和缓存的地图源；不要绕过第三方服务条款、配额、登录、授权或访问限制。

先说结论

如果你想学习“离线地图瓦片到底怎么下、怎么组织、怎么导出”，不要一上来就写爬虫。

更稳的学习路径是：先找一个能把任务、范围、地图源、并发、失败重试和输出格式都摆在台面上的工具，从一个很小的范围跑通完整流程。

我这次用的是这个仓库：Joe5027/map-tile-fetcher。

它是一个 Go 写的自托管 Web 工具，核心用途是帮助你从授权的地图瓦片源里创建下载任务，然后导出为两类常见离线产物：

  • ZIP 文件树：适合先看清楚瓦片目录、层级和文件结构。
  • MBTiles：适合给移动端、桌面 GIS、离线地图应用或后续工具链使用。

这篇不是教你无限制抓取地图服务。真正值得学的是这一套工程流程：如何选范围、估算瓦片量、控制并发、处理失败、保护 token、生成可复用的离线包。

这个工具适合谁

Map Tile Fetcher 比较适合这些场景：

  • 你在学 GIS、地图开发、离线地图或瓦片服务。
  • 你想知道 bbox、缩放级别、瓦片数量之间是什么关系。
  • 你需要把一个很小的授权区域导出成 ZIP 或 MBTiles。
  • 你要测试天地图、Mapbox、OSM、自定义瓦片 URL 等不同源的任务配置。
  • 你想用 Go、SQLite 和静态 Web UI 搭一个轻量的瓦片下载管理工具。

它不适合这些用法：

  • 把公共地图服务当成无限量下载源。
  • 批量绕过登录、付费、配额、反爬或访问限制。
  • 下载自己没有授权缓存和分发的地图数据。
  • 把真实 token、.env、数据库、压缩包、下载瓦片提交进 Git。

学习离线瓦片，第一步不是“下得越多越好”，而是先知道自己是否有权限下载、缓存、使用和分享。

下载离线瓦片前先想清楚三件事

第一件事：地图源有没有授权。

工具支持配置天地图、Mapbox、OSM、Google 示例和自定义瓦片 URL，但“工具支持”不等于“服务允许你随便下载”。正式使用前，要看清楚目标服务的条款、配额和缓存规则。

第二件事：范围有多大。

瓦片数量会随着缩放级别快速增长。一个城市在低 zoom 下可能很轻，一个城市在高 zoom 下就可能变成非常大的任务。新手测试时，先选街区级别或更小范围，不要直接选全省、全国或高 zoom 全量。

第三件事：你最终要什么格式。

如果只是学习瓦片目录结构，先用 ZIP 文件树更直观。如果你要接入离线地图应用、移动端或后续地图工具链，MBTiles 通常更方便。

两条最常用的任务路径

Map Tile Fetcher 里比较核心的用法可以分成两类。

第一类是范围下载，也就是 bbox 或手动画区域。

你可以在 Web 页面上用 Leaflet 框选矩形，也可以画多边形。坐标使用 WGS84 经纬度，瓦片方案走 Web Mercator。这个方式适合学习“我画的区域 + zoom 范围 + 图层选择”最后会变成多少瓦片。

范围下载适合做最小实验：

  • 先选一个很小的矩形。
  • 只选一两个 zoom。
  • 只选一个图层。
  • 输出 ZIP 或 MBTiles。
  • 看任务进度、失败记录和最终产物。

第二类是行政区或 GeoJSON 下载。

如果你已经有行政区边界或 GeoJSON，就可以按区域创建任务。工具会根据选择的层级、图层和输出格式生成下载任务，还能把多个图层拆成父子任务，方便观察每个数据源的进度和失败情况。

行政区下载更适合正式一点的测试，但它也更容易把任务做大。我的建议是：先用 bbox 跑通，再用一个很小的行政区或自定义 GeoJSON 跑第二次。

三分钟本地启动

仓库地址：

https://github.com/Joe5027/map-tile-fetcher

本地 Go 启动方式：

git clone https://github.com/Joe5027/map-tile-fetcher.git
cd map-tile-fetcher\apps\admin-region-tiler
go run .

然后打开：

http://127.0.0.1:8081/

本地默认登录账号是：

admin / adminmap

这个默认账号只适合本地学习。只要你准备部署或给别人访问，就应该复制 .env.example 到 .env，并改掉默认用户名和密码。不要把 .env 提交到 Git。

Docker 方式：

cd apps\admin-region-tiler
Copy-Item .env.example .env
docker compose up --build

主要配置文件在：

apps/admin-region-tiler/conf.toml

地图源、token 和安全边界

工具文档里提到的常见占位符包括：

  • YOUR_TIANDITU_TOKEN
  • YOUR_MAPBOX_TOKEN
  • YOUR_MAPBOX_SKU

这些值应该通过本地配置、环境变量或部署平台 secret 管理。不要把真实 token 写进公开文章、截图、Issue、日志或 Git 仓库。

如果你只是学习任务流程，可以先从最小范围开始，观察工具如何创建任务、估算瓦片量、写入产物、记录失败。不要为了测试方便就把请求延迟调到极低、并发调到极高。

一个更稳的实验设置是：

  • 范围：很小的 bbox。
  • zoom：从低级别开始。
  • 图层：先选一个。
  • workers：先低并发。
  • request delay：保留合理间隔。
  • 输出：先 ZIP，再试 MBTiles。

等你知道每个参数会造成什么影响，再逐步扩大范围。

ZIP 和 MBTiles 怎么选

ZIP 文件树更适合学习。

它能让你直接看到瓦片文件是怎么按层级、x、y 组织的。你可以解压后检查目录结构，也可以用自己的脚本验证某个 zoom 下的文件数量。

MBTiles 更适合交付和接入。

它把瓦片放进一个 SQLite 格式的容器里，很多离线地图工具和移动端方案都能读取。缺点是新手不如文件树直观，但它更接近实际使用场景。

我的建议是：第一次用 ZIP，看懂结构；第二次用 MBTiles，测试实际接入。

任务管理里最值得看的地方

离线瓦片下载不是一个“点一下就完事”的动作。它更像一个批处理任务。

Map Tile Fetcher 里值得关注的是这些能力：

  • 任务进度：看总量、已完成、失败和当前状态。
  • 暂停和恢复：任务过大或网络不稳时很有用。
  • 取消和删除：测试任务不应该一直堆在本地。
  • 失败记录：看清楚失败是网络、上游限制、token 还是请求过快。
  • 失败重试：先调整参数，再重试失败瓦片。
  • 产物管理：下载 ZIP 或 MBTiles 后，确认文件大小和内容是否符合预期。

你真正要学习的不是“下载按钮在哪里”，而是一个离线瓦片任务从创建到失败处理再到产物验证的完整闭环。

常见失败怎么判断

如果遇到 429，通常优先怀疑请求太快、并发太高或触达服务配额。

处理方式不是继续硬跑，而是降低 workers、增加 request delay、缩小范围、减少 zoom，必要时检查服务商配额和授权规则。

如果遇到 418 或类似被阻断的响应，要考虑当前出口 IP、代理、访问路径或服务商规则。不要把它当成“换个姿势继续冲”的提示。

如果遇到 502、503、504，可能是上游服务临时不稳定，也可能是网络路径有问题。可以先暂停，降低速率，稍后重试。

如果是代理或网络错误，就先把本机网络、代理、DNS、证书和目标服务可访问性查清楚。不要在原因不明时扩大任务规模。

我建议的新手最小实验

第一次实验只做这几步：

  1. 克隆仓库并本地启动。
  2. 打开 http://127.0.0.1:8081/。
  3. 使用你有权访问和下载的地图源。
  4. 配好 token，但不要提交到 Git。
  5. 选择一个很小的 bbox。
  6. 只选低 zoom 和单个图层。
  7. 先导出 ZIP。
  8. 看目录结构、任务记录和失败列表。
  9. 再用同样范围导出 MBTiles。
  10. 记录这次任务的范围、zoom、图层、输出格式、workers、delay 和失败原因。

如果这 10 步都跑通，你就已经理解了离线瓦片下载里最关键的工作流。

学习交流时怎么分享才安全

如果你想把自己的经验发给别人，建议分享这些内容：

  • 仓库地址：https://github.com/Joe5027/map-tile-fetcher
  • 工具版本或 commit。
  • 使用的是 bbox、行政区还是 GeoJSON。
  • zoom 范围。
  • 输出格式。
  • workers 和 request delay。
  • 失败类型和处理方式。
  • 不包含 token 的配置示例。

不要分享这些内容：

  • 真实地图服务 token。
  • 付费服务账号、cookie、session。
  • 绕过限制的方法。
  • 未授权下载的瓦片包。
  • 包含个人位置、客户区域或敏感业务数据的 GeoJSON。

一个好的离线地图学习笔记，应该能帮别人复现思路，但不会帮别人滥用地图服务。

最后

Map Tile Fetcher 对我来说最有价值的地方，不只是“能下载瓦片”，而是它把离线瓦片任务拆成了可以学习、观察和复盘的几个环节：

  • 范围怎么选。
  • 瓦片量怎么估。
  • 地图源怎么配。
  • 并发和延迟怎么控制。
  • 失败怎么记录。
  • 产物怎么导出。
  • token 和下载内容怎么保护。

如果你想学习离线地图瓦片下载，建议从这个仓库开始做一个小实验：

https://github.com/Joe5027/map-tile-fetcher

先跑通最小范围，再慢慢扩大。不要一开始就追求大范围、高 zoom、全图层。离线地图最怕的不是慢，而是不知道自己到底在下载什么、有没有权限下载、失败后该怎么收口。