简介：百度离线地图源码包提供了一套在无网络环境下使用百度地图的完整方案，面向需要离线地图开发或部署的开发者、运维人员及户外场景用户。资源共6个文件，压缩包约23.94MB，包含3个txt说明文档、1个war地图服务包、1个zip离线演示工程以及1个properties配置文件。txt文件用于说明使用流程与注意事项，war包可直接部署为本地瓦片服务，zip内含离线地图demo，properties则用于定义地图层级与缓存路径等参数。已有112人学习了该资源。通过源码包，读者可以了解瓦片地图下载机制、层级组织方式与本地存储配置，掌握搭建简易HTTP地图服务的方法；演示项目还展示了如何在不联网的情况下加载百度离线瓦片，适用于户外旅行、内网系统或应急导航等场景。资源同时提醒了数据更新与版权使用要求，便于用户合规使用。
1. 一套能离线跑起来的百度地图，到底要准备什么
在网上搜“百度离线地图源码下载”的人，多半不是想要一个地图App，而是要在内网、会议室大屏、展示一体机上还原一张可缩放、可标注的百度风格地图。外网地图服务在离线环境不可用，直接把在线JS脚本保存到本地也跑不通——地图数据、瓦片请求和代码是分开的。真正需要的是一套由离线瓦片、本地渲染页面、下载脚本组成的前端工程：先按范围下载瓦片，再用HTML页面在本地读取。下面会讲清下载、部署、踩坑三条路，新手能照着做完一版，熟手能拿着参数和边界快速调整。
2. 离线地图三种路线：先选渲染框架，再谈下载常模
拿到一个“百度离线地图源码”包之前，最该先确认的不是瓦片从哪来，而是渲染层用哪种方案。因为“离线地图源码”这四个字在不同项目里指代完全不同的文件结构，选错方向会让后续下载脚本和页面代码全部返工。
2.1 三种常见方案：瓦片本地渲染、离线版JS壳、官方SDK离线包
第一种是“百度瓦片 + 前端渲染引擎”。把百度地图的瓦片按指定层级和范围下载到本地，用 Leaflet 或 OpenLayers 这类轻量渲染库读取本地目录里的图片。这套方案代码量小，跨平台，支持任意范围裁剪，业务方给一张范围表就能出包。缺点是要自己写下载脚本，而且瓦片在线抓取有严格的频控，必须控制并发和重试。
第二种是“社区流传的离线版百度地图JS壳”。它把在线JS API中的核心对象剥离出来，配合本地瓦片目录，让代码仍然写new BMap.Map()。对于想把原来在线代码原样平移过来的项目，这套方案最省改造成本。缺点是版本老旧，部分瓦片地址规则被官方调整后需要自己修复，而且封装层对现代浏览器兼容性一般。
第三种是“官方SDK离线包”。主要用于移动端原生应用，符合正式授权流程，质量最好，但桌面Web端没有公开的离线发布包，集成流程也重，适合公司有正式合作、需要长期维护的场景。大多数流传的“百度离线地图源码”项目其实走的是第一条路：一份下载瓦片的Python脚本，加一个HTML页面，把渲染库的投影参数和瓦片路径装进同一个工程。
| 方案 | 文件构成 | 改造成本 | 适合场景 |
|---|---|---|---|
| 瓦片+渲染引擎 | 瓦片目录 + HTML/JS | 需要处理坐标投影 | 内网Web大屏、业务可裁剪 |
| 离线版BMap JS壳 | 旧版JS封装 + 本地瓦片 | 代码改动小但兼容性风险高 | 老项目快速平移 |
| 官方SDK离线包 | SDK库 + 数据包 | 集成重且需要授权 | 移动端正式交付 |
2.2 一套完整的“百度离线地图源码”工程包含哪些文件
以瓦片+渲染引擎路线为例，一个能交付的工程至少包含四类东西。第一类是瓦片目录tiles/{z}/{x}/{y}.png，它是地图的底片，占体积最大；第二类是渲染页面index.html，负责创建地图容器和加载图层；第三类是投影与工具库，因为百度瓦片用百度墨卡托编号，直接套标准Web墨卡托会偏移，需要一个适配层；第四类是下载脚本和控制范围的文件，比如download_tiles.py和config.json。
一个典型的目录结构长这样：
baidu-offline-map/ ├─ index.html ├─ js/ │ ├─ leaflet.js │ └─ crs.builder.js ├─ tiles/ │ ├─ 12/ │ │ ├─ 154/351.png │ │ └─ ... │ └─ 18/ └─ scripts/ ├─ download_tiles.py └─ config.jsontiles目录必须先用脚本预生成，不能靠渲染引擎现拉；crs.builder.js决定了瓦片能否对齐到正确的投影位置，这一步很多新手会漏，出现“底图能显示但标注坐标全偏”的情况。config.json里放着层级范围、瓦片行列号范围，以及下载脚本要用的样式参数，是整个流程的输入源头。
2.3 为什么我最终选了瓦片+渲染引擎的组合
个人经验是：如果是交付给某公司的内网大屏，最怕的不是地图加载慢，而是“数据源断供”。离线版BMap JS壳把在线注册逻辑都打到了一起，遇到瓦片地址规则调整，要去逆向看它的网络请求封装，排查很痛苦。而 Leaflet+本地瓦片是纯文件逻辑，打开浏览器网络面板就能定位到具体请求，标注和业务图层也更容易用标准GeoJSON维护。
再一点是裁剪灵活。一次下载某县级市城区范围，只取12到18级，比全量离线包小两个数量级。渲染引擎把瓦片当成普通图片，浏览器有原生缓存，内存占用可控。后续如果要分屏对比、叠加热力图，Leaflet的扩展比旧版BMap封装好做。这个选型不适合的场景也有：需要完整POI搜索、路线规划等在线能力时，离线方案都不合适，必须保留服务端代理或走正式授权。
3. 下载百度瓦片：坐标规律、并发脚本和落盘自检
选定了方案，接下来重点就变成了“瓦片怎么下对”。这一步是百度离线地图源码工程里最容易翻车的环节，因为瓦片坐标不是普通经纬度地图编号，单纯照着网上找的脚本改个URL，经常下载下来一大片空白图。
3.1 百度瓦片编号规则与范围换算
百度网页地图瓦片遵循“每放大一级，瓦片数量翻四倍”的规律。层级z从3或4开始，第18级在市域范围内已经接近建筑轮廓精度。瓦片路径由z、x、y三个整数确定，在线地址里能看到类似?qt=tile&x={x}&y={y}&z={z}&styles=pl的查询串。与普通Web墨卡托最大的差异是瓦片编号原点和投影坐标系不同，直接用“经纬度转行列号”的通用算法套上去，下载范围会整体错位。
我一般不在脚本里做经纬度转百度瓦片行列号的复杂换算，而是用在线页面把地图缩放到需要的层级，取四角坐标组成范围表，再让脚本基于z、x、y整数区间去下载。操作步骤是：打开目标区域地图，按 F12 打开开发者工具，切到 Network 面板，刷新一次后过滤tile请求，复制一张瓦片URL；然后拖动地图到期望范围的西南角，记录当前视野里最小的x、y，再拖到东北角，记录最大的x、y；不同层级分别记一组，写入config.json。
这样做的好处是显而易见的：范围以瓦片级为准，不再依赖坐标转换，且人工比较容易核对“哪个整数瓦片围住了要的区域”。如果你非要写一套通用转换器，也得先用在线页面对比验证过再上车，否则一次错位就是几万张废图。
3.2 下载脚本：并发、重试与断点续传
下面这个脚本是最小可用的下载器，我拿它拉一个中等城市的12到18级是没有问题的。注意并发数不要贪多，百度瓦片服务对高频请求有限流，4路并发加退避重试是最稳妥的组合。
import os import time import requests from concurrent.futures import ThreadPoolExecutor, as_completed TILE_URL = "https://maponline{sub}.bdimg.com/tile/?qt=tile&x={x}&y={y}&z={z}&styles=pl" SAVE_ROOT = "tiles" HEADERS = { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "Referer": "https://map.baidu.com/", "Accept": "image/avif,image/webp,image/apng,image/*,*/*;q=0.8", } MAX_WORKERS = 4 MAX_RETRY = 3 def tile_file(z, x, y): return os.path.join(SAVE_ROOT, str(z), str(x), f"{y}.png") def download_one(job): z, x, y = job path = tile_file(z, x, y) if os.path.exists(path) and os.path.getsize(path) > 2048: return True os.makedirs(os.path.dirname(path), exist_ok=True) sub = (x + y) % 4 url = TILE_URL.format(sub=sub, x=x, y=y, z=z) for attempt in range(1, MAX_RETRY + 1): try: resp = requests.get(url, headers=HEADERS, timeout=10) if resp.status_code == 200 and len(resp.content) > 1024: with open(path, "wb") as f: f.write(resp.content) return True elif resp.status_code == 404: return None elif resp.status_code == 403: time.sleep(2 * attempt) else: time.sleep(1) except requests.RequestException: if attempt == MAX_RETRY: return False time.sleep(2 * attempt) return False def download_all(config): jobs = [] for z in range(config["min_zoom"], config["max_zoom"] + 1): x0, x1 = config["x_range"][z] y0, y1 = config["y_range"][z] jobs.extend((z, x, y) for x in range(x0, x1 + 1) for y in range(y0, y1 + 1)) failed = [] with ThreadPoolExecutor(max_workers=MAX_WORKERS) as pool: futures = {pool.submit(download_one, job): job for job in jobs} for fut in as_completed(futures): result = fut.result() if result is False: failed.append(futures[fut]) return failed if __name__ == "__main__": config = { "min_zoom": 12, "max_zoom": 18, "x_range": { 12: (154, 158), 13: (309, 317), 14: (619, 635), 15: (1239, 1271), 16: (2479, 2543), 17: (4959, 5087), 18: (9919, 10175), }, "y_range": { 12: (351, 355), 13: (703, 711), 14: (1407, 1423), 15: (2815, 2847), 16: (5631, 5695), 17: (11263, 11391), 18: (22527, 22783), }, } failed_list = download_all(config) print(f"失败 {len(failed_list)} 张，可重新执行脚本续传")这段代码的核心逻辑是：先判断本地文件是否已存在且大于2KB，是则跳过，否则发起请求；下载结果分三类，成功、不存在、失败，失败的任务会被收集起来，脚本跑完后重跑一次就能续传。sub=(x+y)%4是瓦片子域拆分规则，用来分散请求压力。MAX_WORKERS=4是爬取瓦片的安全并发数，调成8或10短时间看着快点，但很快会撞上403。timeout=10用于避免某个子域卡死拖慢整个线程池。
3.3 落盘后的自检：404、空瓦片与数量核对
脚本跑完不等于瓦片就绪。百度瓦片服务对不存在的范围不会返回必错内容，有时给一张200的空白PNG，有时给一张1KB左右的占位图。因此落盘自检必须做，我会在下载完成后跑一遍文件扫描：
import os from collections import Counter SAVE_ROOT = "tiles" def scan_tiles(): sizes = Counter() empty = [] for root, _, files in os.walk(SAVE_ROOT): for name in files: if not name.endswith(".png"): continue path = os.path.join(root, name) size = os.path.getsize(path) sizes[size // 1024] += 1 if size < 2048: empty.append(path) print("文件大小分布（KB -> 数量）：") for size in sorted(sizes): print(f"{size}KB -> {sizes[size]}") print(f"疑似空瓦片数量：{len(empty)}") return empty自检时最该看的是“疑似空瓦片”数量。如果某一层空瓦片成片出现，说明这个层级的x_range、y_range超出了实际地图范围，需要回到在线页面重新确认四角。如果只是零星几个，通常是海域或边界外，可以直接忽略。把下载脚本和扫描脚本都放进scripts目录，后续做增量更新时还能复用。
4. 部署离线地图页面：本地HTTP服务、投影配置与标注叠加
瓦片下载之后，第一步不是急着打开HTML，而是先把本地HTTP服务起起来。很多新手直接用浏览器双击index.html，结果底图只加载一圈就断掉，原因是浏览器对file://协议的跨目录请求限制很严格。地图瓦片属于本地资源，但也走HTTP请求，用本地静态服务是最省事的做法。
4.1 用本地HTTP服务打开页面：为什么不能直接双击HTML
在工程根目录下执行：
python -m http.server 8080然后浏览器访问http://localhost:8080/index.html。这里的8080端口按需改，注意不要和本机其他服务冲突。使用file://打开时，渲染引擎能读取同路径下的JS，但部分浏览器会把瓦片目录的读取当成跨域请求，出现“瓦片路径对但一张都加载不出来”的玄学问题。切到HTTP服务后，所有资源走同域，问题自动消失。
如果你部署到内网的Windows服务器，也可以用 Apache、Nginx 或 IIS 托管同一个目录，只要保证index.html能被访问、tiles目录能用 URL 路径访问到即可。最省事的验证方式是直接在浏览器地址栏输入http://localhost:8080/tiles/12/154/351.png，能出图就说明瓦片目录映射正确。
4.2 投影与瓦片对齐：初版先用EPSG3857，别一开始就陷进BD09
百度在线地图用的是百度墨卡托投影，和标准Web墨卡托不完全一样。但诡异的地方在于，瓦片图片本身已经按百度投影像素裁好了，渲染引擎要做的只是按照编号把它们拼起来。因此初版部署时，我建议直接用 Leaflet 默认的EPSG3857，先让底图和缩放转起来，不要一上来就写复杂的百度投影适配，否则会卡在坐标公式上。
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>百度离线地图</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.x/dist/leaflet.css" /> <script src="https://unpkg.com/leaflet@1.9.x/dist/leaflet.js"></script> <style> html, body, #map { width: 100%; height: 100%; margin: 0; } </style> </head> <body> <div id="map"></div> <script> var map = L.map('map', { center: [/* 换成你业务区域的纬度 */ 0, /* 经度 */ 0], minZoom: 12, maxZoom: 18, zoomControl: true, attributionControl: false }); L.tileLayer('tiles/{z}/{x}/{y}.png', { minZoom: 12, maxZoom: 18, tms: false }).addTo(map); </script> </body> </html>这段代码里最重要的两个参数是tms: false和瓦片路径模板。百度瓦片的y轴从上往下编号，和标准瓦片服务保持一致，所以必须关掉 TMS 反转，否则地图上下拼反。center里的经纬度是给地图初始定位用的，需要换成你自己项目的实际坐标；不同地区这个值差很多，写死之前先在线页面对一下。
如果后续要精确叠加业务坐标，再单独加一个坐标校正常量，放到页面的配置区里。底层思路是：底图先保证能显示，坐标精度问题靠业务点位校准解决，不要两者混在一起调。
4.3 把业务标注叠上去：加标记、弹窗与GeoJSON
底图能拖动缩放后，就可以往页面里加业务标注。我用得最多的是点标注和弹窗信息，代码量不大，但能覆盖大屏展示的大部分需求：
function toLocal(latlng) { var lat = latlng[0] + 0.0060; var lng = latlng[1] - 0.0065; return [lat, lng]; } L.marker(toLocal([/* 指导点位纬度 */, /* 经度 */])) .addTo(map) .bindPopup('这里是一个测试标注点') .openPopup();toLocal里的两个常数是我常用的近似修正值，解决的是百度坐标和标准Web墨卡托之间的系统性偏移。不同区域偏移量会有差异，正确做法是先取一个已知点位，对照在线地图把修正值微调到位，再批量导入数据。如果你部署的场景只是看底图和区域轮廓，不需要叠加业务坐标，可以完全跳过这个函数。
GeoJSON 方式更推荐，因为业务数据从数据库导出后直接转成GeoJSON，渲染引擎原生支持：
fetch('data/points.geojson') .then(function(res) { return res.json(); }) .then(function(geojson) { L.geoJSON(geojson, { onEachFeature: function(feature, layer) { layer.bindPopup(feature.properties.name || ''); } }).addTo(map); });这样维护成本最低，数据文件更新后刷新页面即可，不需要重新排版页面代码。
5. 百度离线地图部署避坑：5个让我返工的实测问题
离线地图这东西，问题不在“能不能跑通”，而在“跑通之后有多少张瓦片是废的、页面换个环境还能不能起来”。这一章把我反复踩过的坑集中写出来，每条都是现象、原因、解决三步。
5.1 白屏但瓦片网络请求全部200
现象：页面打开后地图容器空白，开发者工具 Network 面板里瓦片请求一个不少，状态码全是200，但页面就是没有图。我一度以为是浏览器缓存问题，清了缓存还是一样。
原因：瓦片请求虽然返回200，但返回内容不是图片，而是一段带styles参数冲突的错误提示。最常见的场景是下载时用的瓦片URL风格和页面加载时拼接的URL风格不同，比如下载脚本里带了styles=pl，页面里却沿用默认样式后缀，服务端把200当成正常响应返回，但内容不是有效PNG。
解决：统一瓦片URL里的样式参数，下载脚本和页面图层只保留一种。瓦片文件名里不要出现额外后缀，保存为{y}.png，页面模板也严格写成tiles/{z}/{x}/{y}.png。另外用图片查看器打开一张瓦片确认是正常地图，而不是大于几十字节的报错文案。
5.2 地名与底图错位，样式参数不一致
现象：底图显示正常，但叠加的业务标注点和图上实际位置对不上，偏差大概几百米。这是所有离线地图项目都会遇到的坐标问题，不是瓦片下载错了。
原因：百度瓦片使用百度墨卡托，而页面里业务数据通常来自WGS84或GCJ02坐标。如果页面直接用原始经纬度丢进L.marker，必然产生固定偏移；有些区域偏移还会因为层级不同被放大，越过某个缩放级别后看起来尤其明显。
解决：在数据入口统一做修正，而不是改瓦片投影。我一般维护一个correction.json，里面放采样点位的经纬度差值，加载地图时读取这个文件，再对业务坐标执行toLocal转换。换地区时只需要重新采样几个点更新差值，不要改页面代码。这个坑的核心教训是：不要把坐标修正逻辑分散在十几处，集中一个模块管住。
5.3 下载到一半被限流：并发与UA问题
现象：脚本跑了几分钟，突然连续出现大量403错误，之后所有瓦片请求都返回响应错误。这不是网络断，也不是瓦片URL有问题，而是单IP请求频率触发了服务端的限流机制。
原因：常见原因是两个，一是MAX_WORKERS调太高，二是请求头里的User-Agent是Python默认UA，太容易被识别成批量抓取。网上很多旧脚本默认并发是16，一跑就废。
解决：把并发降到4，请求头带上浏览器UA和Referer。另外脚本里加退避逻辑，遇到403时当前线程休息2秒、4秒、6秒再重试，最多重试3次。实测这个配置能稳定跑完一个中等城市的市区范围。如果你的范围特别大，更稳妥的做法是按层级分批下载：先下12到15级，再下16到18级，中间停一两分钟给IP降降温。
5.4 瓦片目录有文件但页面仍显示灰块
现象：目录里瓦片文件都在，页面底图却被一块块灰色背景填满，像被橡皮擦过。用图片工具打开瓦片文件能正常显示，但页面渲染出来就是灰的。
原因：一类是因为瓦片PNG被下载成了带透明通道的空图，文件大小正常但内容大部分是透明像素；另一类是浏览器给图片加了缓存，而缓存里存的是早期失败请求返回的灰色占位图，刷新页面后没有重新拉文件。
解决：先扫描瓦片文件大小分布，把小于2KB的文件单独移出来看看，如果全是透明像素就重新下载该范围。再强制硬性刷新，或者用无痕窗口打开页面。部署到内网后，如果更新过瓦片，也要记得在页面URL后面加一个版本参数，比如index.html?v=20250601，避免旧缓存拖着新瓦片不放。
5.5 磁盘空间爆炸：范围与层级的取舍
现象：下载范围看起来不大，但跑完后磁盘空间告急，一个市级区域轻轻松松吃掉几十GB。很多用户以为是瓦片图片太占空间，其实真正原因是层级和范围没做好取舍。
原因：瓦片数量随层级指数增长。15级到16级翻四倍，16级到17级再翻四倍，如果范围表是从在线页面截图整屏直接抄的，没有按实际业务范围裁掉郊区和山地，产生大量无用瓦片，体积自然失控。
解决：每一层级的x_range、y_range尽量单独配置，不要共用一组上下限。部署前先跑一层16级，看看瓦片数量是否符合预期，再决定要不要下17级和18级。还有一个实用技巧：小比例尺区域用12到15级，大屏近景才需要16级及以上；如果只是看个轮廓，12级就足够。
6. 进阶：体积控制、增量更新与一张图的自检习惯
离线地图维护成本不体现在第一次部署，而体现在“范围变了、瓦片更新了、怎么保证不出明显断层”。我的一些习惯是把全流程拆成三步：先算出目标体积，再按需下载增量，最后用脚本检查完整性。
体积预估算可以很简单，每一层的瓦片数等于(x1 - x0 + 1) * (y1 - y0 + 1)，N层加起来再看平均单张大小，就能判断这轮要不要下满。实测百度瓦片单张在10KB到60KB不等，市区密集区域偏大，郊区偏小，预算时按40KB单张估算比较稳。如果范围很大，先下12到15级，跑一次完整自检流程，确认没白屏、没错位之后，再决定要不要继续拉高楼层级。
增量更新我一般只下载新增范围，不重新全量拉。把在线页面四角记录成一份bounds.json，和上一版比对，脚本只处理新增的瓦片行列号，老瓦片不动。更新完成后用du -sh tiles看体积变化，再抽查新区域边界的几张瓦片能否正常打开。
最后的自检习惯很土但很有效：每次部署完成，按12、14、16、18四个层级各截一张全屏图，人工扫一眼四个角有没有缺块；然后用扫描脚本统计各层级瓦片数量，数量反常的层级先怀疑范围表抄错，再怀疑脚本并发被限流。这个习惯帮我挡住过好几次上线后才发现地图缺角的尴尬。
有一回我图省事，从12级直接下到19级，跑到一半磁盘告急，中止后重跑又发现前一版缓存乱了，最后只能把瓦片目录删掉，从范围表重新逐层下载。后来无论如何我都会先下低层级验证全链路，再补高层级，宁可多跑一次脚本，也不在深夜上线前返工。希望帮到你。
本文还有配套的精品资源，点击获取
