简介百度离线地图示例3.0版是一套基于百度地图脚本接口开发的离线地图应用示例面向需要在无网络或网络不稳定环境下使用地图服务的开发者特别适合前端工程师和地理信息系统学习者在受限网络条件下进行地图功能开发。资源共包含1174个文件以1093个JPG格式的地图切片和48个JS脚本文件为核心另附PNG、GIF、CUR等图标资源、HTML入口文件和TXT说明文档压缩包仅9.3MB便于快速下载和本地部署。目前已有8238人学习下载体现了其在离线地图学习与实践中的参考价值。通过该示例可以深入理解地图切片按缩放层级组织的原理掌握初始化脚本如何配置本地切片资源并完成地图渲染同时了解功能模块如何实现标记、绘制、轨迹分析等扩展能力。示例还涵盖了离线地图的数据更新、存储管理和性能优化等实用话题为车载导航、户外活动等应用场景提供了可直接借鉴的实现思路与方法。1. 百度离线地图示例 V3.0 到底解决了什么问题你手上是不是也有一套“百度离线地图示例 V3.0”但打开index.html一片灰或者跑起来之后地图不显示瓦片这套示例解决的是内网环境下的地图展示问题没有外网、不能访问在线地图服务但业务系统又必须有一张可缩放、可标记、可画轨迹的底图。V3.0 代表百度地图 JavaScript API 的一个经典版本它把在线 API 脚本和底图瓦片一起做成静态资源放到本地服务器后浏览器加载的全是localhost或内网 IP 的资源整个过程不依赖任何公网接口。它适合两类人一类是要快速交付内网 GIS 界面的前端开发另一类是负责私有化部署的系统集成工程师。你不需要自己实现地图引擎也不需要处理复杂的投影转换只要把示例包里的路径、中心点、缩放级别改对就能得到一张和在线百度地图交互习惯基本一致的离线地图。但别被“示例”两个字误导它不是一个双击就能跑的小网页里面藏着坐标偏移、瓦片层级、跨域请求这些坑。这篇文章就把我从“拿到示例”到“能在内网项目里稳定跑起来”的完整过程讲清楚。2. 离线地图的组成与选型API 包、瓦片和底图策略2.1 百度地图 JS API 离线包的核心文件与运行机制先弄清楚离线包和在线版的区别。在线百度地图 JS API 在页面里执行时会动态从 CDN 加载按需拆分的模块瓦片图片则来自地图服务域名请求类似maponline0.baidu.com/tile/?qtvtilex...y...z...。离线包把这些依赖全部“搬”到了本地一个提供全局BMap对象的 JS 主文件若干个配套的 UI 控制图片、图标以及按层级组织的瓦片 PNG 文件。V3.0 这个版本核心是传统 JS API 的离线封装不是后来的 WebGL 版。传统版在兼容性上更稳支持 IE11 和所有主流浏览器而且社区里流传的离线示例大多基于这个时代的 API。它不依赖 WebGL 渲染对低配电脑和集成显卡更友好。离线包的加载机制一般是先加载一个主脚本它会读取同目录下的配置确定瓦片服务的根路径然后创建地图实例。你可以打开 DevTools 在 Network 面板观察看到脚本和图片都来自本地说明离线包已经在正常工作了。判断手上一套离线包是否可用最简单方式是看目录里有没有这两个东西一个是bmap*.js或baidu_map*.js之类的主脚本另一个是带tiles名称的文件夹。如果只有脚本没有瓦片那它顶多算 API 框架不能显示地图底图。比如我常用的一套示例包结构是baidu-offline-demo/ ├─ lib/ │ ├─ bmap_v3.0.js │ ├─ bmap_init.js │ └─ tiles/ │ ├─ 1 │ ├─ 2 │ └─ ... ├─ demo/ │ └─ index.html └─ server/ └─ nginx.conf主脚本负责创建BMap命名空间bmap_init.js负责初始化瓦片路径和加载基础配置tiles目录则存储按z/x/y组织的图片。如果你的示例包把瓦片和 JS 混在一起也不奇怪只要在 HTML 中按照相对路径正确引用即可。2.2 瓦片来源与数据量估算全量还是按需离线地图最大的工作量其实不在 API 代码而在瓦片数据。瓦片就是一张张 256×256 的 PNG 图片金字塔模型按层级切分。百度地图的瓦片组织方式和标准 TMS 有差别它用的是百度墨卡托投影瓦片编号与在线版一致所以离线包里的瓦片不能直接从网上随意抓。选瓦片来源通常有三条路第一条是使用示例包自带的瓦片一般只覆盖某个演示城市适合验证功能第二条是使用瓦片下载工具从在线地图服务预取然后在业务部署时一起拷到内网这是最常用的做法第三条是把单位已有的 GIS 瓦片转换成百度瓦片格式但转换过程要处理投影和偏移坑比较多。数据量是必须提前估算的。一张 256 级的 PNG根据地图内容复杂度约 10KB 到 50KB。一个城市如果只覆盖十几层通常需要几十万张如果是全国范围静态数据会到几个 TB不建议一次性全量离线。我一般会按业务区域估算比如一个园区需要 15 级到 17 级只切边界外扩 3 公里控制在几万张以内。下表是一个粗略参考覆盖范围缩放级别瓦片数量约存储体积约单个园区15-171 千 - 1 万50MB - 300MB单个地级市10-1510 万 - 50 万2GB - 8GB全国5-17数千万张数百GB以上这个估算只是数量级参考实际以瓦片内容复杂度为准。预取瓦片时要注意控制并发数不要对整个地图服务发起高并发请求否则很容易触发限流。另外必须遵守地图服务的使用条款离线数据只能用于内部业务不能对外提供在线地图服务。3. 在本地跑通百度离线地图 V3.0部署步骤与最小示例3.1 环境准备与目录结构要跑通离线示例你不需要数据库也不需要后端服务一个静态服务器就够。常见的环境是 Windows 或者 Linux配上 Python、Node.js 或 Nginx 三选一。先把示例包解压到本地确认目录结构完整。如果从同事那里拷贝最好检查一下lib/tiles目录里有没有实际 PNG 文件有些压缩包把空目录剔除了看起来有目录结构实际拉取瓦片时全是 404。我习惯把离线示例放到一个独立目录不要放在系统盘的权限受控路径下否则静态服务器可能没有读取权限。推荐放在/data/map-demo或者用户目录下的projects/map-demo。示例包根目录应该能看到lib、demo、server这三个常见目录其中demo里是入口 HTML。准备好之后先不要急着打开index.html而是启动一个本地 HTTP 服务。直接双击 HTML 文件用file://协议打开瓦片请求很可能被浏览器拦截或产生跨域问题这是很多新手翻车的起点。用静态服务器才能模拟真实生产环境。3.2 最小 HTML 页面加载本地 API 与中心点配置以下是最小可用的demo/index.html。这个页面假设你的离线包把主脚本放在../lib/bmap_v3.0.js瓦片放在../lib/tiles/。请根据你手中实际的目录结构调整路径。!DOCTYPE html html langzh-CN head meta charsetUTF-8 title百度离线地图示例 V3.0/title style html, body, #map { width: 100%; height: 100%; margin: 0; overflow: hidden; } /style !-- 关键必须加载本地脚本不能改成第三方在线地址 -- script src../lib/bmap_v3.0.js/script /head body div idmap/div script // 创建地图实例容器 id 必须对应 div var map new BMap.Map(map); // 业务中心点使用百度坐标 BD-09 // 这里用占位坐标替换成你项目所在的经纬度 var point new BMap.Point(116.404, 39.915); // 第 15 级适合展示一个园区或城区数值越高画面越细 map.centerAndZoom(point, 15); // 开启滚轮缩放注意缩放范围要匹配瓦片覆盖层级 map.enableScrollWheelZoom(); /script /body /html这段代码的逻辑很简单new BMap.Map(map)创建地图实例centerAndZoom设置中心点和初始缩放级别。你可能注意到这里没有配置瓦片路径这是因为离线包的主脚本在加载时会自动按自身目录推导瓦片根路径所以你不需要显式指定。如果页面能显示地图说明离线包内部机制已经正常。需要注意示例包里的bmap_v3.0.js可能是压缩过的如果它在初始化时依赖某个配置文件你还需要确保bmap_init.js也被加载。有些离线包要求主脚本加载前先声明一个全局变量比如window.BMapConfig { mainUrl: ./tiles/ }。在运行最小示例之前最好看一眼demo目录里的原版 HTML按它的顺序来引用脚本不要自己凭感觉打乱顺序。3.3 用本地服务器启动并验证在根目录启动一个静态 HTTP 服务。如果你有 Python 3直接执行cd /data/map-demo python -m http.server 8080启动后浏览器访问http://localhost:8080/demo/index.html。如果页面出现一张可拖动的地图说明基础环境已经通了。下一步是验证它是不是真的彻底离线打开 DevTools 的 Network 面板刷新页面然后过滤 URL检查有没有包含map.baidu.com或bdimg.com的请求。正常情况应该是零。如果发现还有请求往外跑说明你的离线包并不完整或者某个插件还在尝试加载在线资源。生产环境建议用 Nginx 而不是 Python 的临时服务器。参考配置如下server { listen 8080; server_name _; root /data/map-demo; # 瓦片是静态文件允许浏览器缓存 location /tiles/ { expires 7d; add_header Cache-Control public, max-age604800; } # 主入口 location /demo/ { index index.html; } }这里把/tiles/路径单独配置了 7 天缓存瓦片数据基本不变缓存能明显提升重复打开速度。root指向你的示例包目录注意root和alias的区别root会把 URL 路径直接拼在根目录后面。如果你的瓦片实际在/data/map-demo/lib/tiles/而 URL 访问的是/lib/tiles/那么root /data/map-demo是对的如果你想把 URL 简化为/tiles/就要用location /tiles/ { alias /data/map-demo/lib/tiles/; }。这个细节容易踩坑我建议先按原目录结构跑通再去优化 URL。4. 离线地图的必调参数缩放级别、中心点、坐标系与控件4.1 坐标系与百度 BD-09 的处理GPS 数据偏了半条街百度地图使用 BD-09 坐标系这是在国内标准火星坐标GCJ-02基础上再叠加一层偏移得到的。你的业务数据如果是 GPS 采集的 WGS-84比如手机定位或者车载 GPS直接拿到地图上打点会看到点位整体偏移了几十米到几百米。这是离线地图“玄学”里最常出现的问题地图底图没问题业务点印上去偏了。处理方式有几种。如果你的业务系统里已经有坐标转换模块最好在后端统一转好。如果没有前端也可以做一个近似转换百度坐标的转换公式是公开可用的以下是一个常见的 WGS-84 转 BD-09 算法// WGS-84 转 BD-09 近似算法 function wgs84ToBd09(lng, lat) { var x lng; var y lat; // 第一次偏移模拟 GCJ-02 的效果 var z Math.sqrt(x * x y * y) 0.00002 * Math.sin(y * Math.PI * 3000.0 / 180.0); var theta Math.atan2(y, x) 0.000003 * Math.cos(x * Math.PI * 3000.0 / 180.0); // 第二次偏移加入百度的二次加密 return { lng: z * Math.cos(theta) 0.0065, lat: z * Math.sin(theta) 0.006 }; }这个算法是公版近似解误差在米级以内对大多数展示型业务足够了。但注意它只适合 WGS-84 转 BD-09如果你的原始坐标本身就是高德 GCJ-02要先把 GCJ-02 转回 WGS-84再经上面的函数转成 BD-09。不要直接套两次否则偏移会更大。我在实际项目中遇到过一种更隐蔽的情况离线包里的瓦片是直接从在线地图预取的而业务系统里某些图层用的是高德坐标两者混用后底图和 POI 标注不在一个位置。要治本就要在预取瓦片时明确地图源并在离线包文档里写清楚当前用的坐标系。建议在项目启动时就把坐标转换加到公共工具函数里所有打点入口统一走转换不要在各页面各写一遍。4.2 缩放级别与瓦片覆盖范围为什么一缩小就白屏瓦片是按金字塔结构切片的如果你只在离线包里放了 10 到 15 级瓦片用户把地图缩到 5 级就会看到一片空白。这不是离线包坏了而是没有对应层级的瓦片。所以在地图初始化时必须明确设置可用的缩放范围。常见做法是在创建地图后立刻设置最小和最大缩放级别var map new BMap.Map(map); // 设置中心点16 级适合展示园区内建筑细节 var point new BMap.Point(116.404, 39.915); map.centerAndZoom(point, 16); // 限制缩放范围防止用户缩到没有瓦片的层级 map.setMinZoom(10); map.setMaxZoom(18); // 禁用超出层级后的自动重复请求行为 map.enableContinuousZoom();setMinZoom(10)和setMaxZoom(18)的值要按你瓦片的实际覆盖层级来写。判断方法很简单打开 Network 面板把鼠标滚轮缩小一级看断言的瓦片请求是几级如果请求是z11但报了 404说明这一整层缺失。我建议在验收时把瓦片覆盖的最小层级写进需求文档例如“地图至少支持 10-17 级缩放”避免交付后用户随便一滚就得到一张白板。另外百度地图的瓦片层级有一个细微的偏移量在部分离线实现里显示层级zoom对应的目录名可能是zoom - 1因为在线版底层在做坐标转换时多了一个偏移。如果你的页面显示了地图但瓦片错位可以试试调整全局配置里的层级偏移参数常见的字段名是zoomOffset或tileOffset。这个偏移值只有 0、1、2 三种可能逐个试一下就能定位。4.3 控件的取舍哪些能用哪些必须拆掉离线包往往只内置了底图和基础交互并不包含所有在线控件。比如在线版有路况图层、实时搜索下拉、3D 楼块按钮这些在离线包里都是不可用的。如果你不加处理直接引入控件轻则按钮点了没反应重则控件初始化时请求在线资源导致整个页面报错。我一般只保留三个控件缩放、比例尺、缩略图。缩放和比例尺是地图交互刚需缩略图能帮助用户在离线地图上理解当前位置。代码示例// 添加地图导航控件缩放和平移 map.addControl(new BMap.NavigationControl({ anchor: BMAP_ANCHOR_TOP_LEFT, type: BMAP_NAVIGATION_CONTROL_LARGE })); // 添加比例尺 map.addControl(new BMap.ScaleControl({ anchor: BMAP_ANCHOR_BOTTOM_LEFT })); // 添加缩略图注意缩略图也会拉取瓦片必须确认瓦片覆盖完整 map.addControl(new BMap.OverviewMapControl({ anchor: BMAP_ANCHOR_BOTTOM_RIGHT, isOpen: false }));这段代码里的anchor和type是百度地图常规参数。如果你不需要缩略图建议不要加因为缩略图会在地图角落创建一个小的低层级地图它会请求更小层级的瓦片而这些瓦片很可能不在你的离线包里。另外离线包里有些图标文件缺失会导致控件的图片变成破碎图标。这通常不影响功能只影响观感。如果你希望完全干净可以把示例包里lib/images或者lib/icons目录覆盖到你的发布目录。地图的版权信息最好保留虽然离线包可能在角落没有显示但合规上内部系统引用地图数据仍应保留来源标识。5. 百度离线地图 V3.0 的避坑指南5 个常见问题与排查5.1 现象控制台报BMap is not defined这是我见过最多的错误原因几乎都是脚本加载顺序或者路径问题。你明明引用了bmap_v3.0.js但浏览器执行到new BMap.Map时BMap还没被创建。打开 Network 面板先看脚本的状态码如果是 404说明src路径不对当前页面位置与脚本相对位置不匹配。如果是 200 但执行仍报错说明离线包主脚本依赖另一个前置脚本例如bmap_init.js而这个前置脚本没有加载。解决方法是按离线包自带的示例页面顺序加载不要自己精简。例如有些包要求先加载一个baidu_map.js再加载bmap_v3.0.js顺序反了就会抛异常。还有一种情况是脚本本身被浏览器安全策略拦截比如从局域网共享路径直接加载这时把离线包拷到本地服务器即可。5.2 现象地图区域是一片灰色没有底图灰色通常意味着地图容器已经创建但瓦片请求全部失败。排查步骤是先定位一张瓦片地址按 F12 打开 Network把瓦片请求过滤出来看到一个类似tiles/15/138/56.png的请求复制 URL 在浏览器新标签打开。如果直接打开也是 404就是服务器路径没对齐。如果直接打开能显示图片但地图上依然灰则可能是层级偏移参数不对。常见的原因是瓦片目录是lib/tiles/15/138/56.png但页面是从demo/index.html发起的如果主脚本把瓦片根路径推导成了demo/tiles/那肯定找不到。此时需要手动设置瓦片根路径。以我见过的一个示例包为例它要求这样设置// 在某些离线包中主脚本会读取这个全局配置 window.BMapConfig { mainUrl: ../lib/tiles, // 相对当前 html 的路径 tileSize: 256, zoomOffset: 1 };你在自己项目里要把mainUrl改为实际路径。如果不确定字段名可以在主脚本里搜索mainUrl或者tileUrl看一下它读取什么值。另一个坑是 Windows 环境下路径分隔符反斜杠导致的请求异常统一用正斜杠/即可。5.3 现象地图能显示但部分区域是白块或碎块这种情况说明瓦片数据不连续。可能是预取瓦片时范围不够或者某张瓦片下载失败被忽略了。我的排查方法是定位白块的坐标把当前缩放级别和瓦片编号记下来然后去瓦片目录里找对应文件是否存在。如果文件不存在是瓦片缺失需要补数据。如果文件存在但浏览器不显示则可能是缓存了旧的错误响应。加一层清缓存操作或者在 Nginx 里设置try_files指向一个透明底图location /tiles/ { root /data/map-demo; try_files $uri /maps/blank.png; # 缺失瓦片返回透明图 }用一张 256×256 的透明 PNG 作为兜底至少不会出现视觉上刺眼的红色 404 图标。但这不是根除最终还是要补全瓦片。我给一个建议预取任务结束后写一个扫描脚本统计目录中瓦片文件数与预期数是否一致避免交付后才发现中间断了层。5.4 现象路况按钮点了没反应卫星图一片黑V3.0 离线包通常只包含标准矢量底图不包含实时路况和卫星影像。路况是动态图层必须在有网环境下从服务端拉取卫星瓦片和矢量瓦片投影方式不同数据量也更大很多离线包根本不放。如果你在页面上保留路况开关就会给用户一个“能点但没效果”的坏按钮。解决办法是隐藏或移除所有不支持的控件。检查代码里有没有调用new BMap.TrafficControl()或者map.setMapType(BMAP_SATELLITE_MAP)有就删掉。更稳妥的做法是初始化时把地图类型固定为普通矢量map.setMapType(BMAP_NORMAL_MAP);如果需求里确实必须显示卫星底图那就得单独准备一套卫星瓦片离线包并确认该离线包支持对应地图类型。不要指望矢量底图能顺便撑起卫星图层。5.5 现象从页面加载离线地图时报跨域错误当你用file://直接打开 HTML或者把地图前端部署在 A 项目而瓦片服务部署在 B 项目的不同端口时浏览器会拦截图片请求。离线地图的本质是无数个图片请求跨域报错会让整张地图都变成灰白。正确处理是让瓦片服务器返回 CORS 头。如果瓦片由 Nginx 服务在location /tiles/中加上location /tiles/ { add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Methods GET, OPTIONS; }如果地图前端和瓦片服务是同一个域按理说不应该跨域。如果还是报错检查主脚本 URL 是否用了http://localhost而页面访问的是http://127.0.0.1两者在浏览器看来属于不同源统一为同一个地址即可。生产环境建议用反向代理把瓦片路径代理到前端同域路径下这样最干净。6. 把离线地图集成到真实项目数据请求代理与动态轨迹回放6.1 用本地接口封装瓦片请求当离线地图和业务系统深度集成时我一般不直接把瓦片目录暴露给前端而是让后端提供一个瓦片接口。原因有两个一是后端可以控制访问权限二是在未来切换瓦片源时可以不动前端代码。接口设计非常简单// 前端请求瓦片的地址由后端从文件系统读取返回 const tileUrl /api/map/tile?z${zoom}x${x}y${y};后端实现时只需要注意路径参数必须严格做白名单校验防止../目录穿越。例如// 校验 x,y,z 为正整数 if (!Number.isInteger(zoom) || !Number.isInteger(x) || !Number.isInteger(y)) { return; }这样做之后离线地图对业务系统来说就是一个普通数据服务后续如果你想从百度瓦片换成自建矢量瓦片只要后端接口返回图片格式不变前端完全不用动。6.2 动态轨迹回放在离线底图上做车辆移动离线地图最常见的业务场景是车辆轨迹回放。底图不依赖网络画点画线也都在本地计算性能比在线地图更可控。下面这段代码展示如何加载一条轨迹并逐点显示// 轨迹点数组使用百度坐标 var points [ new BMap.Point(116.4040, 39.9150), new BMap.Point(116.4070, 39.9160), new BMap.Point(116.4100, 39.9140) ]; // 绘制静态轨迹线 var line new BMap.Polyline(points, { strokeColor: #1E90FF, strokeWeight: 4, strokeOpacity: 0.8 }); map.addOverlay(line); // 用定时器逐个添加 marker模拟车辆行进 var idx 0; var timer setInterval(function () { if (idx points.length) { clearInterval(timer); return; } var marker new BMap.Marker(points[idx]); map.addOverlay(marker); idx; }, 1000);这段代码的关键在于BMap.Polyline和BMap.Marker都是离线包内置的不需要额外引入图形引擎。定时器间隔 1000 毫秒表示每秒移动一个点实际项目可以根据 GPS 时间间隔调整。注意每次添加 marker 后数量多时要考虑清理比如只保留最近 100 个点否则长时间运行会占内存。6.3 性能与内存优化习惯离线地图有一个好处瓦片都是本地文件所以加载速度比在线地图快网络开销几乎为零。但代价是浏览器会缓存大量图片长时间运行页面可能变得卡顿。我养成的一个习惯是在地图容器被切换或关闭时显式释放地图实例。// 页面卸载前销毁地图释放内存 function destroyMap() { if (map) { map.clearOverlays(); map.destroy(); } }另外如果轨迹点非常多比如一天上万条 GPS 点一次性全画会非常卡。把Polyline的points数组按时间切片先画整条轨迹的简化线再按时间窗口逐步补充详细点。这样既保证观感又控制性能。我上一次交付项目就是栽在最小缩放级别上用户一缩到没有瓦片的层级整张地图变黑屏。后来我把瓦片覆盖范围和缩放边界写进了测试用例每次发版前自动检查一遍再没出过类似问题。离线地图 V3.0 本身不难难的是把边界条件都守好。希望帮到你。本文还有配套的精品资源点击获取