做GIS开发的人应该都遇到过这种尴尬：项目部署在隔离内网，业务系统要求有大屏地图展示，结果在线瓦片一张都加载不出来，地图区域白花花一片。我最近完成的一个项目就是这种典型场景，最终用 OpenLayers 做了一套离线地图方案，把谷歌、高德、百度三种底图瓦片全部落到本地，按项目需求随时切换。不是简单贴一个图层，而是把瓦片获取、目录存储、坐标系对齐、加载性能整条链路都打通了。这套方案适合用 OpenLayers 做 GIS 开发的朋友，也适合正在被“内网+地图”需求折磨的前端或后端同学。这篇文章会把关键原理和完整实操过程都写出来，尽量让新手拿着就能用。
1. 为什么要把在线地图做成离线：场景与技术选型
1.1 离线地图解决的四个现实场景
第一个场景是网络隔离。很多政企项目、科研项目、生产系统都部署在专网里，物理隔离是硬性要求，外网根本不通，在线地图自然不可用。第二个场景是弱网环境。就算能连外网，会议室、地下机房、偏远地区的网速也常常不稳定，大屏演示的时候瓦片加载不出来非常尴尬。第三个场景是响应速度。在线地图每次打开都要请求远程服务器，不管带宽多高，延迟都在几十毫秒到几百毫秒；本地瓦片从内网磁盘读取，基本是毫秒级响应，地图拖拽和缩放的手感完全不一样。第四个场景是数据边界。有些业务数据不允许进入外部地图服务，离线部署可以确保所有地图数据和业务数据都留在可控环境内。
我最早也走过弯路，想着“既然在线地图慢，那就配置一个代理缓存”。但代理缓存依然依赖源站，源站一调整或者网络策略一变，整套东西立刻失效。后来我意识到，对于固定区域、固定层级的底图需求，最稳的办法就是提前把瓦片下载到本地，做成一个私有的瓦片仓库。离线地图真正解决的，是你不再依赖任何一家在线服务的可用性。
1.2 为什么选择 OpenLayers 而不是 Leaflet、Cesium
做 Web GIS 的前端框架，社区最常用的无非是 OpenLayers、Leaflet、Cesium 三家。Leaflet 轻量、上手快，适合简单的点线面展示，但我要在一个项目里同时兼容谷歌、高德、百度三种瓦片规则，还需要做坐标系纠偏、瓦片网格自定义，Leaflet 虽然也能做，但扩展起来明显更费劲。Cesium 主打三维地球，用来做二维栅格底图属于杀鸡用牛刀，而且打包体积大，内网部署的静态资源成本更高。
OpenLayers 在这三者里是最平衡的选择。它本身对瓦片图层的处理非常原生，ol.source.XYZ、ol.source.TileImage这些类就是专门处理切片数据的，投影转换、瓦片网格、加载函数都可以自定义，文档也足够多。还有一个现实好处：OpenLayers 是纯前端库，不依赖构建工具，下载一个发行包放到内网目录就能用。这一点在离线环境里特别重要，因为很多时候你根本没法访问 CDN。
1.3 谷歌、高德、百度三套瓦片源的本质差异
很多人以为离线地图就是“把 URL 从在线换成离线”，其实没这么简单。三套瓦片源至少有三个方面不一样。
第一是坐标系。谷歌地图用的底图坐标体系接近 WGS84，高德地图对外使用的坐标是 GCJ-02，百度地图则是在 GCJ-02 基础上再做一次 BD-09 偏移。这些差异会导致同一套 GPS 坐标在三种底图上显示的位置不一样，偏差从几十米到几百米不等。
第二是瓦片编码规则。谷歌和高德的瓦片 x、y、z 规则基本一致，网格原点在左上角；百度瓦片的 y 轴方向相反，原点在左下角。如果你拿着谷歌的瓦片编号规则去拼百度瓦片地址，地图能不能出来另说，位置大概率是错乱的。
第三是 URL 风格。每种底图的数据接口参数都不是一套，直接写死字符串很容易踩到某个源下线或者参数变化。
所以我把它们拆成了一整套可配置的图层体系，每种底图单独建目录、单独写加载逻辑、单独处理坐标系，而不是硬把它们叠在一张图上。下面详细讲每一步。
2. 离线瓦片数据的获取与整理
2.1 瓦片金字塔与 XYZ 编号规则
离线地图的基本单元是瓦片。地图服务商把一张完整地图按缩放级别切成无数小方块，每个小方块叫一个 tile。级别从 0 开始，0 级是整个地球缩成一张瓦片；每放大一级，上一级的 1 张瓦片会被切成 4 张。所以全球范围的瓦片数量是 4 的 z 次方，第 15 级全球大概有 10 亿张，这个数量对工程来说是不可接受的。
实际项目中我们只需要某块城市或园区范围。比如一个城市到 12 级可能只有几千张，到 16 级就是几万张，到 18 级就是几十万张。级别越高，单张瓦片覆盖的地理范围越小，地图上能看到的道路和建筑细节越多。但每提升一级，瓦片数量变成 4 倍，磁盘占用和下载时间也跟着涨。所以离线范围规划必须做两个限制：一是范围限制，只下载目标区域的瓦片；二是级别限制，业务需要看到哪个精度，就下载到哪个级别。不是把网上所有级别都拉下来才叫离线。
瓦片保存到本地一般遵循{z}/{x}/{y}.png的目录结构。z 是缩放级别，x 是列号，y 是行号。这套规则在 OpenLayers 里叫 XYZ 规则，也是大多数地图服务商使用的公开切片规则。另一种叫 TMS 规则，区别在于 y 轴方向相反，TMS 的 y 从底部往上递增。离线工具导出目录时必须搞清楚导出的到底是 XYZ 还是 TMS，否则加载时地图会上下撕裂。
2.2 三套瓦片的 URL 模板与坐标原点差异
既然要离线下载，首先要识别在线瓦片的 URL 规则。下面给出三套底图的 URL 模板示例，实际使用时请以服务商当前接口为准：
谷歌：https://mt1.google.com/vt/lyrs=m&hl=zh-CN&gl=CN&x={x}&y={y}&z={z} 高德：https://webrd0{1-4}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z} 百度：https://maponline0{1-4}.bdimg.com/tile/?qt=pc&x={x}&y={y}&z={z}&styles=pl&scaler=1&p=1这里的{x} {y} {z}是占位符，下载工具会用实际瓦片编号替换。谷歌和高德的瓦片编号从左上角开始，y 在竖直方向向下递增；百度的瓦片编号从地图的左下角开始，y 在竖直方向向上递增。因此百度的 URL 模板虽然也写{y}，但它的 y 编号和标准 XYZ 编号是相反的。
举个例子：某缩放级别为 18，标准 XYZ 规则下第 200 行瓦片，对应百度坐标应该是2^18 - 1 - 200 = 262143 - 200 = 261943。在写离线加载代码时，如果工具导出的是标准目录，而你直接拿百度的在线编号去匹配，就会 404。这里很容易出问题，后面第 4 节还会重点讲。
2.3 离线瓦片下载的实操工作流
我自己常用的下载流程分四步：画范围、选底图、设级别、导出目录。不需要写复杂的爬虫脚本，直接使用常见的离线地图下载工具即可。这类工具通常内置了谷歌、高德、百度的瓦片源，你只需要在地图上画一个矩形或多边形范围，选择需要的底图类型，设置最小和最大缩放级别，然后导出。
导出格式要注意。优先选择“XYZ 目录”或“标准瓦片目录”格式，这样目录层级恰好是{z}/{x}/{y}.png，后端代码几乎不用改造。如果工具默认导出的是 TMS 格式，目录里的 y 方向是反的，OpenLayers 加载时就要用自定义 tileUrlFunction 把 y 反转。
下载瓦片时有几个经验值得分享：第一，卫星图比路网图大得多，一张瓦片可能几百 KB，如果项目只需要路网底图，就不要把卫星图也下载回来。第二，有些工具会生成很多空白瓦片，白白占用磁盘和 inode，建议导出完成后检查一下空白瓦片比例，必要时候用一张透明 PNG 统一占位。第三，离线下载只应服务于有正式授权或者明确合规范围内的内部系统。如果是商用系统，最好向地图服务商申请离线授权，或者使用官方提供的离线 SDK。这一点不是走形式，而是真踩过合作方被追责的例子。
3. OpenLayers 加载离线地图的完整实现
3.1 本地瓦片目录、静态服务与库文件离线化
瓦片下载完成后，我习惯把目录结构整理成下面这样：
offline-tiles/ ├── google/ │ ├── 10/ │ ├── 11/ │ └── ... ├── amap/ └── baidu/在每个底图目录里，继续按z/x/y.png存放瓦片。目录名建议统一用英文小写，避免中文路径在浏览器和 HTTP 服务之间产生编码问题。
瓦片不能直接用file://协议打开页面去加载。因为浏览器的同源策略会把本地文件与 HTTP 页面当成不同源，而且直接读本地文件也没有并发限制和缓存控制。正确做法是通过本地 HTTP 服务映射瓦片目录。
如果项目里已经有 Nginx，可以直接加一段静态资源配置：
server { listen 8080; server_name 127.0.0.1; root /data/offline-tiles; location /tiles/ { add_header Access-Control-Allow-Origin *; try_files $uri /tiles/blank.png; } }没有 Nginx 的环境，开发调试时也可以用 Python 临时顶一下：
cd /data/offline-tiles python3 -m http.server 8080再补充一个容易被忽略的点：OpenLayers 库本身也要离线化。到官网下载对应版本的发行包，把ol.js和ol.css放到业务系统的静态目录，页面里引用本地路径。否则瓦片离线了，地图框架却还在依赖外网 CDN，网一断一样白屏。
3.2 初始化地图与 XYZ 图层配置
基础地图初始化代码并不复杂。以下是以谷歌离线瓦片为底图的示例：
import Map from 'ol/Map'; import View from 'ol/View'; import TileLayer from 'ol/layer/Tile'; import XYZ from 'ol/source/XYZ'; import { fromLonLat } from 'ol/proj'; const googleLayer = new TileLayer({ source: new XYZ({ url: '/tiles/google/{z}/{x}/{y}.png', projection: 'EPSG:3857', crossOrigin: 'anonymous' }) }); const map = new Map({ target: 'map', layers: [googleLayer], view: new View({ center: fromLonLat([120.0, 30.0]), // 示例点位，生产环境替换为项目实际坐标 zoom: 12, maxZoom: 18 }) });projection默认就是 EPSG:3857，OpenLayers 里绝大多数非标准情况都需要关注这个值。高德和谷歌的在线瓦片，下载后按标准 XYZ 目录存放，加载配置基本和这个一样，只需要把 URL 改成对应底图目录。真正麻烦的是百度瓦片和坐标系。
3.3 高德、百度瓦片的特殊处理
高德瓦片如果导出的目录是标准 XYZ，加载代码几乎不用改：
const amapLayer = new TileLayer({ source: new XYZ({ url: '/tiles/amap/{z}/{x}/{y}.png' }) });但要注意，高德瓦片本身基于 GCJ-02 加密坐标系。地图瓦片里的道路、建筑位置是经过偏移后的结果，你如果直接用 GPS 的 WGS84 坐标往里叠加点，会发现所有点都往某个方向漂了几百米。这个问题不是 OpenLayers 的 bug，而是坐标体系不统一。
百度瓦片则需要特殊处理 y 轴方向。OpenLayers 的 XYZ 图层默认按左上角原点计算瓦片坐标，而百度目录里的 y 是从下往上递增的。加载百度瓦片时需要写一个自定义 URL 函数：
const baiduLayer = new TileLayer({ source: new XYZ({ tileUrlFunction: function (tileCoord) { const z = tileCoord[0]; const x = tileCoord[1]; const y = Math.pow(2, z) - tileCoord[2] - 1; return `/tiles/baidu/${z}/${x}/${y}.png`; } }) });这段代码的意思是把 OpenLayers 计算出来的左上角原点 y 值，转换成百度左下角原点的 y 值。这里有个前提：下载工具导出的百度瓦片目录，是按百度原始坐标编号保存的。如果工具导出时已经帮你反转成了 XYZ 编号，那就不需要再反转，否则会重复反转导致错乱。拿到离线包后，最好先抽查几个级别的瓦片路径，确认一下到底是哪种规则。
3.4 坐标系统一：三个坐标系必须分清楚
做离线地图最容易翻车的就是坐标系。网上很多教程直接忽略这个问题，最后结果就是地图能显示，业务点全飘在外面。
需要分清楚的三种坐标系：
- WGS84：GPS、手机定位、遥感影像等常用地理坐标系；
- GCJ-02：高德地图、腾讯地图对外使用的加密坐标系；
- BD-09：百度地图在 GCJ-02 基础上再次偏移后的坐标系。
它们的偏差并不是固定的十几米，而是随经纬度变化的，通常在几十米到几百米之间。正确做法是：选择哪个底图，项目里的业务数据就统一转换到哪个坐标系，然后继续使用 OpenLayers 的 EPSG:3857 做前端显示。
举三个具体场景：
- 底图用谷歌离线瓦片，业务数据来自 GPS 或普通经纬度，那数据不需要转换，直接用 WGS84 转 Web Mercator 后叠加；
- 底图用高德离线瓦片，业务数据来自高德 API，那也不需要转，因为数据已经是 GCJ-02，瓦片和高德坐标一致；
- 底图用百度离线瓦片，业务数据来自高德 API，那需要先把 GCJ-02 转成 BD-09，再叠加到百度瓦片上。
千万不要试图在 OpenLayers 里通过自定义投影的方式“纠正”瓦片偏移。瓦片本身是栅格图片，图片里的内容已经固定了加密后的位置，改投影只能改变网格划分，不能纠正内容偏移。正确做法永远是在业务数据侧做坐标转换。
4. 常见问题与排查技巧实录
4.1 瓦片 404、灰块、错位：先查目录而不是查代码
我踩过最无语的坑是瓦片加载出来一半灰块，另一半正常。检查了一下午代码，最后发现是下载工具导出时把部分目录命名成了10/123，另一部分却多了一层10/123/123.png，大小写和扩展名也没有完全统一。OpenLayers 的{z}/{x}/{y}.png是严格匹配路径的，任何一层对不上就是 404。
遇到这种情况，第一步打开浏览器开发者工具的 Network 面板，看请求的实际 URL。如果 URL 路径和磁盘上的目录结构完全一致但依然 404，再看大小写、文件后缀、空白瓦片。如果 URL 路径本身已经错位，比如 y 值明显很大，那就是瓦片编号规则不对，需要检查是否要反转 y，或者下载工具是不是导出了 TMS 格式。
还有一类“地图能显示但位置错乱”的问题，其实是缩放级别不匹配。比如离线包只下载到 14 级，但前端把maxZoom设置成了 18，用户一放大到 15 级以上，地图就只能显示空白或重复拉伸。离线瓦片包的下载级别范围，必须和前端 View 的minZoom、maxZoom对齐。
4.2 底图偏移几十米到几百米：坐标系没有对齐
偏移问题是最容易误判的。如果你发现地图显示正常，但叠加的业务点整体往某个方向偏移，而且偏移量在几百米左右，那基本可以断定是坐标系冲突。比如用 WGS84 的点去叠高德瓦片，或者用 GCJ-02 的点去叠谷歌瓦片，都会出现这种情况。
排查方法很简单，找一个你已知准确坐标的参照点，比如项目区域内的某个路口，分别用三种方式定位：在谷歌底图上定位一次，在高德底图上定位一次，在百度底图上定位一次。看哪个底图上点位和现场位置一致，然后确认项目业务数据背后的坐标体系。如果业务数据已经大量存在，没法全部重采，那就写一个坐标转换模块，统一在数据入库或读取时候转换。
这里有个经验：业务系统的坐标体系最好在项目启动时就定死，不要“到时候再说”。后面数据一多，坐标转换的边际成本会越来越高。坐标转换函数不要自己造轮子，用成熟的开源坐标转换库，输入输出都测试通过再上线。
4.3 离线包体积爆炸：控制瓦片范围与级别
离线地图对范围非常敏感。我曾给一个大区域的系统做离线包，下了 16 级卫星图，结果硬盘直接吃掉了 200 多 GB，Nginx 一响应瓦片请求，磁盘 IO 就满了。后来把范围裁剪到项目实际业务区，卫星图级别降到 14，路网图保留 16，整体体积直接降到 12 GB。
如果确实需要覆盖很大范围，建议按“瓦片裁剪”思路处理。下载工具支持画多边形范围时，尽量画准确的业务边界，不要拉一个巨大的矩形。矩形范围会把大量无用道路、山体、农田都下载下来。
PNG 瓦片的体积还和地图内容相关，密集城区比乡村地区大很多。追求极致压缩时，可以把瓦片从 PNG 转成 WebP，但要看地图渲染和浏览器兼容性。另一个思路是直接用透明 PNG 做空白占位，避免大量无内容的 404 请求拖慢加载速度。
4.4 瓦片更新后不生效：缓存与版本策略
离线瓦片不是永远不变。道路新建、建筑拆迁、地名变更都会导致底图过时。更新瓦片的方式通常是重新下载对应范围和层级的瓦片，覆盖到原目录。但这时候很容易出现一个现象：明明磁盘文件已经更新了，浏览器里却还是旧地图。
原因是浏览器对同 URL 的图片做了强缓存。解决办法有两个：一是在瓦片 URL 上加版本号，比如/tiles/google/{z}/{x}/{y}.png?v=20250201，版本号一变，浏览器会认为这是新资源；二是在 Nginx 层面对瓦片目录禁用长缓存，设置较短的Cache-Control。如果更新频率不高，用版本号更简单直接；如果瓦片经常更新，就配置 Nginx 的缓存策略。
另外，瓦片目录更新时最好保持原子性，不要在一个地图正在被大量访问的时候就删掉旧目录。先把新瓦片放到临时目录，校验完整后再整体替换，否则地图访问会出现大量 404。
5. 离线地图扩展：从单项目到基础设施
5.1 瓦片服务独立拆分
做完第一个离线地图项目后，我发现这种能力完全可以抽出来做成公共基础设施。瓦片库本身是纯静态文件，不依赖任何业务服务，把 Nginx 配成一个独立的瓦片服务端口，多个业务系统都能复用。前端只要配置一个/tiles/路径，业务代码里连地图源细节都不用关心。
独立瓦片服务的好处是，权限控制、缓存策略、流量监控都可以统一管理。比如内网大屏项目可能同时有几十个页面在请求瓦片，如果每个系统都自己存一份瓦片，既浪费磁盘又难维护。拆分成独立服务后，瓦片只维护一份，其他系统通过 HTTP 访问即可。
5.2 多项目复用的底图切换设计
我在实践里会写一个简单的底图配置模块，通过环境变量或配置文件控制当前项目默认使用哪套底图：
const MAP_SOURCE = 'google'; // 可选 google / amap / baidu const sourceMap = { google: () => new XYZ({ url: '/tiles/google/{z}/{x}/{y}.png' }), amap: () => new XYZ({ url: '/tiles/amap/{z}/{x}/{y}.png' }), baidu: () => new XYZ({ tileUrlFunction: function (tileCoord) { const z = tileCoord[0]; const x = tileCoord[1]; const y = Math.pow(2, z) - tileCoord[2] - 1; return `/tiles/baidu/${z}/${x}/${y}.png`; } }) };切换底图时，顺便把业务数据的坐标转换函数也一起切换。这样新项目接入时几乎不用改地图逻辑，只要配好底图类型和数据坐标系即可。这里建议在前端做一层坐标转换封装，不要在业务组件里到处写转换代码，否则后期维护会非常痛苦。
5.3 更进一步：矢量瓦片与离线搜索
栅格离线瓦片已经能解决 90% 的底图展示问题，但体积和清晰度始终是短板。现在我更看好矢量瓦片方案。矢量瓦片存储的不是渲染好的图片，而是道路、建筑、标注等几何数据，前端渲染时再根据样式生成画面。同样范围下，矢量瓦片体积通常比栅格瓦片小一个数量级，而且放大不模糊。
但矢量瓦片不是拿来就能用的，需要准备 MVT 格式的数据源，还要处理样式和字体库，技术门槛比栅格方案高不少。如果你的项目对地图体积和流畅度要求极高，可以考虑这个方向；如果只是要快速交付一个内网大屏，栅格离线方案依然是最稳的选择。
最后说点实际操作中的体会
这套离线地图方案我在真实项目里跑了一年多，最大的感受是：地图加载本身并不难，难的是在项目最开始就定好“底图选谁、坐标用什么体系、离线包多大”。只要这三个问题想在前面，后面大概率顺风顺水；想不清楚，后面光是处理偏移和错位就能磨掉好几天。另外，离线地图不是把瓦片下完就一劳永逸，道路和建筑变化之后记得更新数据包。更新时一定要用版本管理，不然用户浏览器里的旧缓存会让你白忙一场。
如果时间允许，我还建议你做一个简单的离线包体检脚本，定期检查瓦片目录的缺失率、文件大小异常和空白瓦片比例。很多问题在数据量小的时候暴露不出来，数据一上 TB，任何目录规则不一致都会被放大成严重的加载事故。选 OpenLayers 做离线底图方案，只要前期的数据组织这一段做扎实，后面基本可以安心交付。
