简介：百度离线地图示例V3.0是一套面向Web地图开发者的离线地图实践项目，基于百度地图JavaScript API V3.0构建，帮助开发者在无网络或网络不稳定环境下依然能够加载、浏览和交互地图，适用于车载导航、户外应用及网络条件受限地区的地图展示场景。资源包共1174个文件，以1093个jpg地图切片为主体，配合48个js脚本、20个png与8个gif界面素材、3个cur光标文件，以及1个html入口页面和1个txt说明，整体约9.3MB，结构紧凑便于本地部署。其中init.js负责初始化地图对象、配置中心点与缩放级别并指向本地切片资源，modules目录则提供标记、路径绘制、图层控制等扩展接口，切片按层级组织以支持不同缩放级别下的平滑浏览。目前已有8231人学习下载，读者可借此掌握离线地图的切片管理、脚本配置与模块调用方法，并理解数据更新、存储索引与性能优化等关键思路，是入门与进阶离线地图开发的实用参考。
1. 百度离线地图示例V3.0：内网环境下的地图底图方案
很多做政企内网项目的同行都遇到过这个场景：服务器部署在完全隔离的内网，前端页面需要展示地图，但百度地图 JS API 的在线瓦片根本请求不出去。这时候能救场的，就是一套完整的离线地图方案。百度离线地图示例V3.0 正是针对这个痛点整理的资源包，它把百度地图 JS API 的离线化改造、瓦片服务搭建、坐标纠偏这几个环节串成了一条可复现的链路。适合谁用？做内网 GIS 展示的前端、需要在地图上叠加业务数据的后端、以及被"地图加载不出来"折磨过的运维。它解决的不是"怎么调百度地图 API"，而是"断网之后地图怎么还能转"。
2. 离线地图的瓦片原理与目录结构：为什么不能直接扒在线瓦片
2.1 瓦片金字塔与百度地图的投影逻辑
在线地图的本质是一堆预先切好的图片，按层级（zoom）、行号（x）、列号（y）组织成金字塔结构。百度地图用的是自己的一套投影和瓦片编号规则，跟标准的 Web Mercator 不完全一样，这也是很多人直接拿在线瓦片地址去爬、结果拼出来地图错位的根本原因。
瓦片金字塔的逻辑是：zoom 0 是一张覆盖全球的图，zoom 1 切成 4 张，zoom 2 切成 16 张，每升一级，瓦片数量翻四倍。百度地图的瓦片编号从左上角开始，x 向右递增，y 向下递增。但百度的投影中心点和墨卡托有偏移，所以如果你用标准墨卡托的公式去算瓦片行列号，拼出来的地图在边缘区域会有明显错位。
常见做法是：先用百度地图 JS API 的BMap.MercatorProjection类做坐标转换，再根据转换后的像素坐标反推瓦片编号。这个类在离线包里通常会被单独抽出来，因为在线 API 加载不了，必须把核心投影逻辑内联到本地。
// 百度地图墨卡托投影转换核心逻辑（离线版内联） // 输入：经纬度 lng, lat；输出：平面像素坐标 var MCBAND = [12890594.86, 8362377.87, 5591021, 3481989.83, 1678043.12, 0]; var LLBAND = [75, 60, 45, 30, 15, 0]; var MC2LL = [ [1.410526172116255e-8, 0.00000898305509648872, -1.9939833816331, 200.9824383106796, -187.2403703815547, 91.6087516669843, -23.38765649603339, 2.57121317296198, -0.03801003308653, 17337981.2], // ... 其余波段系数省略，实际使用时需补全 ]; function convertor(x, y) { // x, y 为百度墨卡托坐标 var band = null; for (var i = 0; i < MCBAND.length; i++) { if (y >= MCBAND[i]) { band = MC2LL[i]; break; } } return { lng: band[0] + band[1] * Math.abs(x), lat: band[2] + band[3] * Math.abs(y) + band[4] * Math.pow(y, 2) + band[5] * Math.pow(y, 3) + band[6] * Math.pow(y, 4) + band[7] * Math.pow(y, 5) + band[8] * Math.pow(y, 6) }; }这段代码的关键在于MCBAND和MC2LL两组系数，它们决定了不同纬度带下的转换精度。参数不能随便改，改了之后地图边缘会出现拉伸或压缩。实际使用时，通常是把经纬度先转成墨卡托像素坐标，再除以瓦片尺寸（百度一般是 256 像素），得到瓦片行列号。
2.2 离线瓦片的目录组织与命名规则
瓦片下载下来之后，怎么存、怎么命名，直接决定了后面服务端能不能快速索引。常见的目录结构有两种：一种是z/x/y.png，另一种是z/y/x.png。百度离线地图示例V3.0 里用的是前者，因为百度官方的瓦片请求路径就是online?qt=tile&x={x}&y={y}&z={z}，按z/x/y组织跟官方逻辑一致，排查问题时不容易乱。
# 典型的离线瓦片目录结构 tiles/ ├── 10/ │ ├── 100/ │ │ ├── 200.png │ │ └── 201.png │ └── 101/ │ └── 200.png ├── 11/ │ ├── 200/ │ │ └── 400.png │ └── 201/ │ └── 400.png每个 PNG 文件就是一张 256x256 的瓦片图。目录层级不能少，因为前端在请求瓦片时，会根据当前地图中心点和缩放级别动态拼出 URL。如果目录结构跟代码里的拼接逻辑对不上，地图就会一片空白，控制台里全是 404。
提示：瓦片下载工具的选择很关键。常见做法是用 Python 写个多线程爬虫，按经纬度范围算出需要的瓦片行列号，再逐个下载。但要注意百度地图的瓦片有防盗链，直接请求可能会被拒，需要在请求头里带上 Referer。
2.3 瓦片服务的本地搭建方式
瓦片下载到本地之后，需要一个 HTTP 服务把它们暴露出去。最简单的做法是用 Nginx 或者 Python 的http.server直接托管静态文件。但这里有个坑：百度地图 JS API 在请求瓦片时，默认会带上一些查询参数，如果你的服务端不处理这些参数，可能会返回 404。
# Nginx 配置：把 /tiles/ 路径映射到本地瓦片目录 server { listen 8080; server_name localhost; location /tiles/ { alias /data/baidu_tiles/; # 关键：忽略查询参数，直接按路径找文件 try_files $uri $uri/ =404; # 允许跨域，因为前端可能跑在另一个端口 add_header Access-Control-Allow-Origin *; } }这段配置的核心是try_files，它让 Nginx 只根据 URL 路径去找文件，忽略后面的查询字符串。Access-Control-Allow-Origin *是为了解决前端跨域问题，因为离线环境下前端页面和瓦片服务很可能不在同一个端口。如果少了这个头，浏览器控制台会报 CORS 错误，地图照样出不来。
3. 百度地图 JS API 的离线化改造：从在线依赖到本地加载
3.1 离线包里的 JS 文件拆解
百度地图 JS API 在线版是通过<script src="https://api.map.baidu.com/api?v=3.0"></script>加载的，这个请求在内网环境里必然失败。离线化的第一步，就是把在线 API 的核心 JS 文件扒下来，改成从本地加载。
百度离线地图示例V3.0 里通常包含这几个关键文件：apiv3.0.js（核心 API）、getscript.js（模块加载器）、map.js（地图渲染逻辑）。其中getscript.js是最容易被忽略的，因为在线版会动态去请求其他模块，离线之后这些请求全部会挂掉，必须把模块加载逻辑改成从本地读取。
// 离线版 getscript.js 的核心改造点 // 原版会动态创建 script 标签请求在线模块 // 离线版改成从本地 modules 目录加载 (function() { var modules = {}; window.BMap = window.BMap || {}; // 重写模块加载函数 BMap._loadModule = function(name, callback) { if (modules[name]) { callback(modules[name]); return; } var script = document.createElement('script'); // 关键：路径指向本地 modules 目录，而不是在线地址 script.src = './modules/' + name + '.js'; script.onload = function() { modules[name] = window['BMap_' + name]; callback(modules[name]); }; document.head.appendChild(script); }; })();这段代码的逻辑是：把原本指向在线地址的模块加载请求，重定向到本地的modules目录。参数name是模块名，比如DrawingManager、MarkerClusterer这些。如果本地缺少某个模块文件，地图初始化时就会卡住，控制台会报BMap is not defined或者某个子模块 undefined。
3.2 初始化地图时的关键参数配置
离线环境下初始化地图，跟在线版有几个关键区别。第一个是tileLayer的配置，必须指向本地瓦片服务；第二个是enableMapClick要关掉，因为离线环境下点击地图可能会触发在线请求；第三个是copyright要改成自己的信息，避免出现百度版权字样。
// 离线地图初始化完整示例 var map = new BMap.Map("mapContainer", { enableMapClick: false, // 关闭地图点击事件，避免触发在线请求 minZoom: 10, // 最小缩放级别，根据瓦片范围设定 maxZoom: 18 // 最大缩放级别，根据瓦片范围设定 }); // 设置中心点（用百度坐标，不是 GPS 坐标） var centerPoint = new BMap.Point(116.404, 39.915); map.centerAndZoom(centerPoint, 12); // 关键：替换默认瓦片图层为本地瓦片 var tileLayer = new BMap.TileLayer({ transparentPng: true, tileUrlTemplate: "http://localhost:8080/tiles/{z}/{x}/{y}.png" }); map.addTileLayer(tileLayer); // 开启滚轮缩放，离线环境下这个交互必须手动开 map.enableScrollWheelZoom(true);tileUrlTemplate里的{z}、{x}、{y}是占位符，百度地图 JS API 会自动替换成当前缩放级别和瓦片行列号。注意这里的{x}和{y}顺序必须跟你的瓦片目录结构一致，如果目录是z/y/x，模板就要写成{z}/{y}/{x}.png，写反了地图会错位。
minZoom和maxZoom要根据你下载的瓦片范围来设。如果只下载了 10 到 15 级的瓦片，但代码里允许缩放到 18 级，用户一放大就会看到空白。常见做法是：在瓦片下载阶段就记录好最小和最大级别，初始化时直接填进去。
3.3 坐标纠偏：GPS 坐标转百度坐标的离线实现
这是离线地图里最容易翻车的地方。GPS 设备采集的是 WGS84 坐标，百度地图用的是 BD09 坐标，两者之间有偏移。在线环境下可以用百度提供的BMap.Convertor做转换，但离线环境下这个接口调不了，必须自己实现转换算法。
// WGS84 转 BD09 的离线实现（简化版） var X_PI = 3.14159265358979324 * 3000.0 / 180.0; var PI = 3.1415926535897932384626; var A = 6378245.0; var EE = 0.00669342162296594323; function wgs84ToBd09(lng, lat) { // 先 WGS84 转 GCJ02 var gcj = wgs84ToGcj02(lng, lat); // 再 GCJ02 转 BD09 var bd = gcj02ToBd09(gcj.lng, gcj.lat); return bd; } function gcj02ToBd09(lng, lat) { var z = Math.sqrt(lng * lng + lat * lat) + 0.00002 * Math.sin(lat * X_PI); var theta = Math.atan2(lat, lng) + 0.000003 * Math.cos(lng * X_PI); var bdLng = z * Math.cos(theta) + 0.0065; var bdLat = z * Math.sin(theta) + 0.006; return { lng: bdLng, lat: bdLat }; }这段代码里X_PI和A、EE是固定系数，不能改。wgs84ToGcj02函数因为篇幅原因省略了，核心逻辑是先用椭球参数算出偏移量，再叠加到原始坐标上。实际使用时，如果发现地图上的标记点跟底图对不上，十有八九是坐标没转，或者转错了方向。
注意：有些项目里 GPS 设备直接输出的是 GCJ02 坐标（比如某些国产模块），这时候只需要做 GCJ02 转 BD09 这一步，不需要先转 WGS84。搞错了会导致偏移量翻倍，地图上差出几百米。
4. 避坑与排查：离线地图部署中最容易翻车的五个点
4.1 瓦片 404 但文件明明存在
现象：浏览器控制台里瓦片请求全是 404，但去服务器上看，对应的 PNG 文件确实在目录里。
原因：最常见的是 URL 模板里的{x}和{y}顺序跟目录结构对不上。比如目录是z/x/y.png，但模板写成了{z}/{y}/{x}.png，请求路径就变成了10/200/100.png，而实际文件在10/100/200.png。另一个原因是 Nginx 的alias路径末尾少了斜杠，导致路径拼接错误。
解决：先手动拼一个瓦片 URL 在浏览器里访问，看能不能打开。如果打不开，检查 Nginx 配置里的alias和location是否匹配。如果能打开但地图还是 404，就是模板顺序问题，把{x}和{y}对调试试。
4.2 地图能显示但拖拽后出现空白
现象：地图初始化时正常，但用户拖拽到某个区域后，新区域的瓦片加载不出来，一片灰白。
原因：瓦片下载范围不够。很多人在下载瓦片时只下了当前城市中心区域，用户一拖拽就出了范围。另一个原因是minZoom和maxZoom设置不当，用户缩放到了没有瓦片的级别。
解决：在瓦片下载阶段，把范围适当扩大，比如中心区域外扩 2 到 3 个 zoom 级别的瓦片。同时在地图初始化时，用map.setMinZoom()和map.setMaxZoom()限制用户操作范围，避免缩放到空白级别。
4.3 标记点位置偏移几百米
现象：在地图上添加的 Marker 位置跟实际地物对不上，偏移量固定，不随缩放级别变化。
原因：坐标没有做 BD09 转换。GPS 设备输出的 WGS84 坐标直接扔给百度地图，就会产生固定偏移。这个偏移量在北京地区大概是往东南方向偏 500 米左右。
解决：在添加 Marker 之前，先把坐标做一次wgs84ToBd09转换。如果转换后还有偏移，检查转换函数的系数是否完整，特别是MC2LL数组有没有被截断。
4.4 离线 JS 加载后 BMap 未定义
现象：页面加载了本地的apiv3.0.js，但控制台报BMap is not defined，地图初始化直接失败。
原因：百度地图 JS API 是异步加载的，在线版通过callback参数通知加载完成。离线版如果直接同步加载，可能在 DOM 还没准备好时就执行了初始化代码。另一个原因是getscript.js里的模块加载逻辑没改对，导致核心模块没加载进来。
解决：把地图初始化代码包在window.onload或者BMap._loadModule的回调里。如果是模块加载问题，打开 Network 面板看modules目录下的 JS 文件有没有被请求，没请求就是加载逻辑没改对。
4.5 瓦片服务跨域被拦
现象：瓦片服务在 8080 端口，前端页面在 3000 端口，浏览器控制台报 CORS 错误，瓦片全部加载失败。
原因：浏览器的同源策略。前端页面和瓦片服务不同端口，属于跨域请求，服务端没有返回Access-Control-Allow-Origin头。
解决：在 Nginx 配置里加上add_header Access-Control-Allow-Origin *;。如果瓦片服务是 Python 的http.server，需要自己写个简单的 HTTP 服务加这个头，或者用 Flask 起一个。
5. 进阶技巧：用 Canvas 做瓦片缓存与按需加载
离线地图跑起来之后，性能优化是下一个要面对的问题。瓦片数量一多，浏览器内存占用会飙升，特别是在低配置的内网机器上。我一般会用 Canvas 做一层瓦片缓存，把已经加载过的瓦片画到离屏 Canvas 上，下次请求同一张瓦片时直接从内存里取，不再走 HTTP。
// 基于 Canvas 的瓦片缓存实现 var tileCache = {}; var CACHE_LIMIT = 500; // 最多缓存 500 张瓦片 function getTileFromCache(z, x, y) { var key = z + '/' + x + '/' + y; if (tileCache[key]) { return tileCache[key]; } return null; } function cacheTile(z, x, y, img) { var key = z + '/' + x + '/' + y; // 超过上限时清理最早的一批 var keys = Object.keys(tileCache); if (keys.length >= CACHE_LIMIT) { for (var i = 0; i < 100; i++) { delete tileCache[keys[i]]; } } tileCache[key] = img; }这段代码的核心是tileCache对象和CACHE_LIMIT常量。CACHE_LIMIT设成 500 是个经验值，太小了缓存命中率低，太大了内存扛不住。清理策略是删掉最早的一批，实际项目中可以用 LRU 算法做得更精细。
另一个技巧是按需加载。不是所有 zoom 级别的瓦片都需要一次性加载，可以根据用户当前的缩放级别，只加载当前级别和相邻级别的瓦片。这样能显著减少初始加载时间。
// 按需加载：只加载当前 zoom 和相邻级别的瓦片 function getVisibleZooms(currentZoom) { var zooms = []; for (var z = currentZoom - 1; z <= currentZoom + 1; z++) { if (z >= minZoom && z <= maxZoom) { zooms.push(z); } } return zooms; }getVisibleZooms返回的是当前可见的 zoom 级别数组，地图移动时只请求这些级别的瓦片。minZoom和maxZoom是全局变量，在初始化时根据瓦片下载范围设定。
验证缓存是否生效，可以打开浏览器的 Network 面板，拖拽地图后观察瓦片请求数量。如果缓存生效，重复区域的瓦片请求应该明显减少。我一般会拖拽几个来回，看请求数是不是稳定在一个较低的水平。
从那以后我每次部署离线地图，都会先跑一遍瓦片范围检查，再手动拖拽测试缓存命中率，最后才交给测试。这套流程帮我省了不少返工时间。希望帮到你。
本文还有配套的精品资源，点击获取
