简介百度离线地图示例V3.0是一套基于百度地图JavaScript API V3.0的离线开发工程面向需要在无网络或弱网环境获得地图能力的开发者可用于车载导航、户外作业与内网部署等场景。压缩包共1174个文件、约9.3MB其中1093个jpg为按层级组织的256×256地图切片48个js文件包含核心初始化脚本init.js与可扩展的modules模块另外少量png、gif、cur等构成控件图标与交互样式并附带html与txt说明文件。这套示例搭建了完整的离线地图技术骨架读者可借此学习切片本地化组织方式、init.js对地图中心点与缩放级别的配置逻辑以及通过modules扩展标记、路径等功能的调用方法从而快速移植出适配自有业务的离线地图应用。目前已有8227人学习下载对希望深入理解百度地图离线方案的中高级前端或GIS开发者具有实用参考价值。 做地图开发这几年我总结出一条铁律能在上线前暴露的问题都不叫问题真正让人头皮发麻的是客户现场告诉你“我们这台机器只能内网访问”。尤其园区、电网、野外作业这类场景数据不能出内网地图却必须能用。百度离线地图示例V3.0 说白了就是一套把百度地图 JavaScript API 第三版跑在完全断网环境下的落地参考核心解决三件事API 脚本本地化、瓦片数据本地化、常用交互能力本地化。项目一旦搭好地图初始化、缩放、打点、画范围、只显示某个市这些功能在纯内网里都能正常跑。这篇文章适合正在做内网地图项目、离线大屏展示或者想彻底搞懂瓦片地图机制的开发同学参考。1. 离线地图 V3.0 的整体设计思路1.1 为什么离线不砍瓦片而是把瓦片搬到本地很多非 GIS 背景的同事第一反应是没网了就别加载地图底图了呗用个静态图片打底不就行了。静态图片在定点展示场景勉强能用但一旦需要缩放、平移图片就露馅了。地图的本质是瓦片金字塔每个缩放级别下用规则网格把世界切成一堆小方块浏览器只需要加载当前视野内的几十张图视觉上就是一张完整地图。所以离线版不是不做瓦片而是把在线瓦片服务搬到本地让 getTilesUrl 从线上 URL 改为相对路径。这样缩放逻辑、缓存机制、overlay 叠加全部保留只是数据源的请求从外网换成了本地。这么做还有一个隐藏的好处加载速度快。内网瓦片延迟通常是毫秒级比公网 CDN 稳得多。尤其做园区导览、巡检可视化这类对交互流畅度有要求的页面离线瓦片反而体验更好。1.2 前端离线架构静态资源 本地瓦片目录整个离线示例的目录结构其实非常朴素一个 HTML 页面、一份本地化的 API 核心 JS、一个 tiles 瓦片目录、再加上若干示例用的 JS 文件。有条件的团队会再用 Nginx 起一个静态文件服务把瓦片目录暴露为http://localhost:8080/tiles/xxxx.png前端代码里相对路径和绝对路径都可以。没有条件的直接在file://协议下打开也能跑——V3.0 离线版对本地文件协议的支持比较友好但要注意 Chrome 对本地文件的某些跨域限制建议用 Nginx 或者直接上 Electron省得被 CORS 坑。架构上的关键决定是不要让前端代码直接连数据库或文件系统而是维持一个静态文件服务层。因为后续要加搜索、定位、轨迹回放都依赖一个能访问本地数据的后端接口静态文件服务是这一切的最小公共底座。1.3 与天地图离线、自建瓦片服务的横向对比这里多说一句选型。离线地图不止百度一家能做很多项目问我为什么不用天地图或 Leaflet 加自建瓦片。我把实际对比的结果放在下面方案坐标系离线落地难度适合场景百度离线 V3.0BD-09 / BD09MC低社区方案成熟已有百度系代码、POI/行政区划数据绑定的项目天地图离线CGCS2000 / WGS84中数据要自己切测绘资质、政务公开类项目Leaflet 自建瓦片WGS84 / GCJ02 均可中高自由度大新项目、定制渲染需求强如果项目里已经用了百度地图开放平台的 JS API历史代码里全是 BMap 相关对象那切到 Leaflet 等于把标注、聚合、轨迹全部重写成本远大于离线化的代价。反过来如果项目还没写代码、精度要求高、数据涉及国家标准坐标系那可以考虑天地图离线。标题里这个示例 V3.0 最大的意义是给存量百度项目提供一条低改造成本的内网化路径。2. 核心原理瓦片、投影与 API 本地化2.1 瓦片金字塔与 URL 规则的秘密要理解离线地图先理解瓦片编号。地图从第 3 级到第 19 级每一级把整个世界切分成2^zoom级别的网格瓦片坐标通常用 z/x/y 表示z 是缩放级别x 是列号y 是行号。在线版百度地图请求瓦片时URL 长这样// 在线百度瓦片 URL示意 https://online0.map.bdimg.com/onlinelabel/?qttilex{x}y{y}z{z}stylespl但你不需要自己去拼这个 URL——JS API 内部会算好当前视野需要的瓦片坐标然后调用我们配置的 getTilesUrl 去取图。离线版要做的就是提前把指定范围内的瓦片按同样的目录规则下载好然后改一个规则不拿 x/y/z 去请求在线服务而是拼出本地路径。2.2 百度坐标系与 BD09MC 投影不少人在离线项目里遇到“地图正常设备 GPS 点总是飘”的问题根因是坐标系。百度地图用的 BD-09 是对国测局 GCJ-02 坐标再做一次二次加密漂移的结果和手机 GPS 拿到的 WGS-84 原始坐标直接画上去偏差通常在几百米量级。离线版依然是 BD-09 坐标系不存在离线就把坐标改成标准坐标的说法。正确做法是在后端把 GPS 坐标转成百度坐标再下发或者用 map 的 projection 对象做一次坐标转换。BD09MC 则是百度地图使用的墨卡托变体投影是所有瓦片切割和坐标计算的底层。大多数前端开发不需要手写投影公式但做瓦片批量下载工具时要特别注意网上很多工具默认输出 XYZ/谷歌编号直接拿来当百度瓦片用会产生偏移甚至显示错乱切片时一定选“百度/BD09MC”格式。2.3 JS API 本地加载的三步走V3.0 离线版不是把整个开放平台 API 原封不动拿下来就可以需要处理三个环节本地化脚本把 mapapi.js 及其依赖的 core、module 等文件放到本地确保页面加载不到外网资源时也能拿到 BMap 全局对象。拦截远程请求部分功能模块在初始化时还是会尝试访问外网需要把初始化参数里的资源地址指向本地。替换瓦片源初始化后通过 addTileLayer 把默认在线图层替换成本地瓦片层。这个过程不同版本细节差异较大建议以你下载到的离线包内说明为准。判断离线是否成功有个很简单的指标打开浏览器开发者工具切到 Network 面板把所有外网域名请求清零地图依然能拖动、缩放就是内网部署可行的标志。3. 从零落地完整实操过程3.1 准备离线瓦片数据先说最费工夫的一步——瓦片数据。有正规数据源的团队可以用切片工具把标准格式的栅格地图切成百度编号的瓦片没有自建数据的则需要借助公网在线地图在授权范围内下载某个行政区的瓦片或者直接采购第三方离线数据包。我的建议是先把范围圈小不要一上来就下全国。比如只做某个市最大级别到 17 级下载完大概几 GB如果还要局部 19 级再单独把热点区域高精度补一层。下载工具的常见输出结构是tiles ├── 3 │ ├── 0 │ │ └── 0.png │ └── 1 │ └── 0.png ├── 4 └── ...路径上的第一层是 zoom第二层是 x第三层是 y.png。这个结构可以直接映射到前端 getTilesUrl 的返回路径。注意文件夹名和文件名的拼写保持全小写Linux 部署时大小写敏感Windows 上没问题换到 Linux 服务器就 404 的坑我踩过不止一次。3.2 引入本地 API 并初始化地图示例页面里加载 API 的推荐方式是这样script src./local/mapapi.js?v3.0/script script // 等 BMap 全局对象出现后再初始化 if (typeof BMap ! undefined) { const map new BMap.Map(map-container, { minZoom: 3, maxZoom: 19, enableMapClick: false }); map.centerAndZoom(new BMap.Point(120.15, 30.28), 12); map.enableScrollWheelZoom(true); } /script注意enableMapClick: false是我推荐默认关掉的。离线环境里点击底图弹出的 POI 信息窗多半是死链而且这个功能还会引入额外的外网请求关掉最省心。如果项目需要点击交互建议用自定义 marker 和自定义信息窗口代替。3.3 自定义瓦片层接入本地目录核心的一段代码是自定义 TileLayerconst offlineLayer new BMap.TileLayer({ isTransparentPng: true }); offlineLayer.getTilesUrl function (tileCoord, zoom) { // 根据缩放级别和瓦片坐标拼接本地相对路径 return ./tiles/ zoom / tileCoord.x / tileCoord.y .png; }; map.addTileLayer(offlineLayer);如果本地瓦片和默认底图的坐标编号存在偏差可以在 return 之前对 x、y 做修正。这个修正关系取决于瓦片来源来自百度在线切片工具的通常不需要改来自谷歌/OSM 标准工具的需要整体偏移。建议拿到瓦片后先用几个不同级别的坐标对比定位确认 x/y 公式正确后再涉及业务代码。3.4 只显示某个市和行政边界裁剪项目里有个高频需求是“只显示某个市”。实现分两层第一层在瓦片数据层只下载目标城市的瓦片视野外的地图自然空白第二层在交互层用行政区边界数据生成 Polygon 覆盖物把边界以外盖上半透明蒙层同时监听地图移动结束事件把视野拉回界内避免用户拖到一片空白区域不知道发生了什么。用 V3.0 的 Polygon 来画边界很直接const boundary new BMap.Polygon(cityBoundaryPoints, { strokeColor: #1E90FF, strokeWeight: 2, fillColor: #1E90FF, fillOpacity: 0.1 }); map.addOverlay(boundary);cityBoundaryPoints 可以从离线化的行政区划数据里取。这里有个经验边界点数据不要太多单城市几千个点足够太多会拖慢 Canvas 渲染。需要中心点就执行map.setCenter(cityCenter)限制视野用map.setBounds(boundary.getBounds())配合拖拽事件里的判断。3.5 覆盖物与交互功能补齐底图能显示了剩下的标注、气泡、聚合这些都是常规操作。V3.0 里 BMap.Marker、BMap.InfoWindow、BMapLib.MarkerClusterer 都支持离线使用只要引入对应 JS 文件即可。要注意的是有些扩展库内部会请求地图 API 的在线资源必须在引入前先替换或直接引入本地版本。做过一个园区大屏项目当时把几百个设备点全部用 MarkerClusterer 聚合离线环境下的聚合性能比在线还顺滑因为网络延迟没了瓶颈只剩浏览器渲染。4. 常见问题与调试实录4.1 白屏、瓦片不出来的排查顺序这类问题接手过很多次总结一套排查顺序现象排查点解决办法页面完全白屏BMap 对象是否已经加载看 Console 是否有BMap is not defined检查本地 API 路径有地图但只有蓝色底瓦片 404Network 面板看瓦片请求路径和目录结构逐级对比部分级别瓦片加载失败下载级别不全检查 tiles 目录下 zoom 文件夹是否存在拖拽后出现空白块视野超出已下载范围加地图边界限制或者补充下载范围绝大多数瓦片不显示的问题根因都是 getTilesUrl 返回的本地路径和实际文件路径对不上。不要猜直接在浏览器里打开一个瓦片 URL比如/tiles/12/338/515.png看能不能出图。出不来就说明目录结构或下载工具输出格式不对。4.2 GPS 定位偏移和不同手机的定位差异离线环境下的定位是个容易忽略的坑。百度 JS API 的 geolocation 功能在离线时往往不可用因为它依赖在线服务返回逆地理编码。我自己做过一轮不同手机的定位测试结论挺典型iPhone 在纯 GPS 模式下的 WGS-84 坐标直接标到百度地图上会偏 300 到 500 米Android 部分机型如果开启了 GPS 加网络辅助返回的坐标反而接近 GCJ-02偏移方向还不一致。所以不要在展示层做坐标猜测统一在后端做 WGS-84 到 BD-09 的转换前端只展示转换后的坐标。4.3 离线环境下的搜索、定位替代方案离线没有在线 POI 搜索是很多业务接受不了的。我的替代方案是从原始数据源导出一份本地 POI 表名称、经纬度、分类、地址用后端接口提供模糊查询前端拿到结果后直接map.addOverlay打点不需要任何在线服务。只要数据质量到位体验不比在线差还能顺带实现“只搜本园区、本市”的限定搜索。4.4 往 Qt、移动端扩展的注意点这套瓦片目录不仅给 Web 用。有团队问过 Qt 加载离线瓦片地图怎么做思路其实一样QWebEngine 里加载本地 HTML把 getTilesUrl 指向本地资源路径即可纯原生客户端则直接按 z/x/y 读瓦片文件用 QGraphicsView 或 OpenGL 纹理绘制。瓦片数据是跨端复用的切好一套数据Web、Qt、iOS/Android 都能吃。关键是把瓦片命名规范和坐标转换算法封装成公共模块别每个端各写一套。有些终端厂商提的 CE 版、定制版本质也是把同一套离线瓦片能力封装进特定设备的壳子里原理没变。手机上那种悬浮小窗、只显示本区的快捷模式同样可以做前端组件自己实现数据源切成当地瓦片和本地 POI 就行。最后分享一个我自己的习惯离线地图项目验收前一定把服务器网线拔了完整跑一遍核心流程——初始化、缩放、打点、搜索、定位。在线 Demo 能跑的功能断网后往往只剩七八十个。百度离线地图示例V3.0 的价值不在于技术多高深而是它把所有“在线依赖”一个个找出来并替换掉让地图真正变成内网里一个安安静静的静态资源目录。多踩几次坑之后你会发现离线化最难的从来不是写代码而是把所有隐形的在线请求都揪出来。本文还有配套的精品资源点击获取