做WebGIS的国内项目基本绕不开天地图。它由国家地理信息公共服务平台统一提供矢量、影像、地形、注记一层套一层关键是免费只要你花几分钟去申请一把开发密钥。我最近在做一个数据大屏项目需要在OpenLayers里同时接入天地图的矢量底图和卫星影像底图并且让用户在界面上随时切换。折腾一圈下来踩了几个坑也总结了一套比较干净的实现方式今天就把从申请密钥到图层切换的完整过程拆开讲一遍希望能帮后面做类似需求的人少走弯路。先说结论OpenLayers加载天地图并没有想象中复杂核心就三件事——密钥和URL配对坐标参考系选对四层瓦片按模式显隐。把这三点理清矢量/影像切换功能半小时就能跑起来。1. 背景与需求拆解一套地图两种表达1.1 为什么选天地图做底图做国内项目选底图绕不开一个现实问题谷歌地图访问不稳定高德、百度的JS API虽然好用但本质上是一个封闭的生态底图样式和坐标系都被平台锁死了。天地图的最大优势是它是国家平台推出的公共服务数据规范性好并且对外提供标准的WMTS/XYZ瓦片服务你可以直接把这些瓦片接到任何主流WebGIS引擎里用不受前端框架限制。在项目里用天地图还有一个很实际的好处矢量底图的要素全道路、河流、行政区划、地名注记都很规整适合做业务分析影像底图是卫星遥感影像看地形和实际地物更直观适合做巡查、爬坡效果和汇报展示。两套底图互补切换着用是很多业务系统的刚需。1.2 OpenLayers在“多底图切换”场景下的优势有人会问现在Leaflet和Mapbox GL也挺流行为什么要用OpenLayers我的判断是在这个场景下OpenLayers对标准瓦片服务的支持最扎实对多图层并发、坐标系转换、自定义控件的掌控力也更强。Leaflet轻量是轻量但做图层组管理、投影切换、底图叠加的时候很多处理要自己手写插件Mapbox GL的底图风格体系非常漂亮但对WMTS这类传统瓦片服务的兼容性反而要额外折腾。OpenLayers的优势可以概括为三点第一它对ol/source/XYZ和ol/source/WMTS的支持非常完善天地图的URL模板直接塞进去就能用第二OpenLayers允许我用显式的visible属性精确控制单个图层的渲染开关做底图切换时逻辑非常干净第三它的坐标系扩展机制成熟默认的EPSG:3857和天地图的瓦片网格能直接对齐不需要自己去处理瓦片坐标换算。1.3 矢量和影像底图的适用场景做需求拆解时我一直建议客户先想清楚“什么场景用矢量、什么场景用影像”而不是简单地做一个切换按钮。矢量底图信息密度高上面有路网、地名、水系、行政边界用户一看就知道自己大概在哪个位置适合日常业务操作——比如标绘、查询、统计分析。影像底图还原真实地表形态适合看目标区域的实际情况——比如农田现状、工地进展、临时堆场很多无人机或GPS采集的业务点放在影像上才“对得上号”。在这个项目里我甚至做了一个临时方案默认加载矢量用户点击“影像”后切换到卫星图同时把影像注记层也一起打开保证切过去之后地名街道名还在。这个细节很多人忽略但直接影响使用体验。2. 开工前的三件套密钥、坐标系、瓦片地址2.1 申请密钥与域名白名单别看网上教程一堆真正写代码前最卡人的一步其实是申请天地图的密钥。步骤如下打开天地图官网注册账号个人实名认证和企业认证都行。注册完成后进入控制台找到“创建应用”。填写应用名称和应用类型关键是要配置“回调域名白名单”。提交后系统会给你一个形如xxxxxxxxxxxxxxxxxxxx的tk密钥。这里提醒一句开发阶段如果域名是localhost白名单一定要加上localhost和127.0.0.1不然本地调试时瓦片请求返回403。线上部署后还要回控制台把正式域名补上。我之前遇到过页面在自己电脑上是好的部署到测试环境后地图一片空白查了半天才发现是新域名没加白名单。另外天地图密钥有并发配额个人实名认证的应用并发量不算高。后面我会专门讲如何避免请求风暴触发限流。2.2 坐标系选型EPSG:3857还是EPSG:4326这是整个项目里最容易出错的环节。天地图官方其实提供了多套瓦片剖分规则国内项目最常见的两种组合是前端视图坐标系天地图瓦片规则说明EPSG:3857Web墨卡托wm主流方案OpenLayers默认投影fit谷歌/Bing网格EPSG:4326经纬度w天地图官方标准经纬度切片适合科学计算场景我的建议是普通Web项目直接采用EPSG:3857 wm规则。原因很简单OpenLayers默认就是3857地图上的center可以用ol.proj.fromLonLat([116.391, 39.907])转换业务方给的GPS坐标WGS84在展示层会自动换算几乎不用写多余代码。如果你选4326那URL模板里就必须配套使用TILEMATRIXSETw同时View的projection要写成EPSG:4326center直接写[116.391, 39.907]。两种都能显示但千万别混搭否则瓦片位置对不上地图会花屏或偏移。顺带解释一下天地图底层的坐标基准是CGCS2000和WGS84在民用精度级别的差异极小肉眼根本看不出偏差所以项目里按WGS84处理坐标完全没问题。如果你做的是科研级高精度应用才需要引入专门的高精度坐标转换库。2.3 看懂天地图URL的九个参数天地图服务本质上是WMTS服务但我们可以直接把请求地址改造成XYZ的URL模板让OpenLayers按z/x/y去拉瓦片。一个标准的墨卡托矢量瓦片请求长这样https://t0.tianditu.gov.cn/vec_wm/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETwmFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk你的密钥拆开看几个关键参数SERVICEWMTS、REQUESTGetTile、VERSION1.0.0固定参数不需要改。LAYER图层的类型vec是矢量底图cva是矢量注记img是影像底图cia是影像注记。STYLEdefault固定样式标识保持默认即可。TILEMATRIXSETwm瓦片剖分规则对应EPSG:3857如果换成w就是4326剖分。FORMATtiles输出瓦片格式天地图使用tiles标识。TILEMATRIX{z}、TILEROW{y}、TILECOL{x}OpenLayers的XYZ模板变量会自动替换成当前视野的瓦片行列号。tk你的密钥必须带。路径里的vec_wm和参数里的TILEMATRIXSETwm要保持一致。网上很多教程用的是vec_w那是4326网格的路径如果你配了3857视图就会对不上。记住了路径尾缀和TILEMATRIXSET是一套组合不能混用。天地图除了t0还有t1到t7共8个子域名可以用来分散并发请求。后面我给的示例代码里会把多个子域传给urls数组让OpenLayers自动轮询。3. 核心功能落地加载矢量、影像并实现切换3.1 初始化页面与地图实例我先用纯HTML CDN方式搭一个可以直接运行的示例这样不管你是Vue、React还是原生项目都能直接看明白逻辑。!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleOpenLayers 加载天地图 矢量/影像切换/title link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/olv8.2.0/ol.css style html, body, #map { width: 100%; height: 100%; margin: 0; } .layer-switch { position: absolute; top: 12px; right: 12px; z-index: 1000; background: #fff; border-radius: 6px; box-shadow: 0 2px 8px rgba(0,0,0,0.15); padding: 4px; font-family: Microsoft YaHei, sans-serif; } .layer-switch button { border: 0; background: transparent; padding: 8px 16px; cursor: pointer; border-radius: 4px; font-size: 14px; color: #333; } .layer-switch button.active { background: #1677ff; color: #fff; } /style /head body div idmap/div div idlayer-switch classlayer-switch button>const TDT_KEY 你的天地图密钥; function tdtUrl(layer, matrixSet) { return https://t0.tianditu.gov.cn/ layer _ matrixSet /wmts ?SERVICEWMTSREQUESTGetTileVERSION1.0.0 LAYER layer STYLEdefault TILEMATRIXSET matrixSet FORMATtiles TILEMATRIX{z}TILEROW{y}TILECOL{x} tk TDT_KEY; } const vectorBaseLayer new ol.layer.Tile({ source: new ol.source.XYZ({ url: tdtUrl(vec, wm) }) }); const vectorLabelLayer new ol.layer.Tile({ source: new ol.source.XYZ({ url: tdtUrl(cva, wm) }) });注意vec_wm和cva_wm的路径。这里我用的是wm规则对应EPSG:3857。如果项目里用的是4326坐标系把wm全部换成w即可。3.3 创建影像底图与注记图层影像底图和注记图层的创建方式一模一样只需要把LAYER换成img和cia。为了后续切换方便我一开始就把四个图层放在两个图层组里const imageBaseLayer new ol.layer.Tile({ source: new ol.source.XYZ({ url: tdtUrl(img, wm) }) }); const imageLabelLayer new ol.layer.Tile({ source: new ol.source.XYZ({ url: tdtUrl(cia, wm) }) }); // 使用图层组管理后续切换只操作组 const vectorGroup new ol.layer.Group({ layers: [vectorBaseLayer, vectorLabelLayer] }); const imageGroup new ol.layer.Group({ visible: false, layers: [imageBaseLayer, imageLabelLayer] });初始状态下imageGroup的visible是false页面默认显示矢量地图。vectorGroup没有设置visible默认为true没问题。这里用图层组而不是直接在Map的layers里塞四个图层是因为切换时我可以直接group.setVisible(true/false)不需要挨个去控制四个图层。地图实例的初始化也要把视图投影明确指定为EPSG:3857const map new ol.Map({ target: map, layers: [vectorGroup, imageGroup], view: new ol.View({ projection: EPSG:3857, center: ol.proj.fromLonLat([116.391, 39.907]), zoom: 11, maxZoom: 18 }) });3.4 图层切换与按钮状态同步切换功能的实现逻辑非常简单切换时让矢量组的visible等于当前模式是否为矢量影像组的visible取反即可。这里我写一个统一函数function switchLayer(type) { const isVec type vec; vectorGroup.setVisible(isVec); imageGroup.setVisible(!isVec); }如果不用图层组直接控制四个图层也不难function switchLayer(type) { const isVec type vec; vectorBaseLayer.setVisible(isVec); vectorLabelLayer.setVisible(isVec); imageBaseLayer.setVisible(!isVec); imageLabelLayer.setVisible(!isVec); }按钮点击的绑定用事件委托不要给每个按钮单独绑事件后续加按钮更灵活document.getElementById(layer-switch).addEventListener(click, function (e) { const btn e.target.closest(button); if (!btn) return; switchLayer(btn.dataset.layer); // 同步按钮样式 document.querySelectorAll(#layer-switch button).forEach(function (item) { item.classList.toggle(active, item btn); }); });按钮样式我在CSS里已经写了.active高亮类点击后当前按钮变蓝另一个恢复白底。这个交互虽然简单但很多项目一上来就容易漏掉“切换状态反馈”用户点了一下没有任何变化感受会以为功能坏了。3.5 图层叠加顺序与zIndex确认前面我用了图层组的方案OpenLayers在渲染时会按照图层数组中的顺序绘制后添加的图层在上层。因此vectorGroup在前、imageGroup在后组内的注记层又在底图层的后面视觉效果是“注记压底图”符合直觉。不过当一个Map里既有底图又有业务图层比如叠加高德覆盖物、热力图、标记点时zIndex就很重要了。我给底图相关图层加一个较低的zIndex比如vectorGroup.setZIndex(0); imageGroup.setZIndex(0);业务图层统一从zIndex: 10起步。这样以后不管往Map里塞什么都不会把天地图的注记盖得乱七八糟。4. 避坑指南坐标系错位、请求限制、样式细节4.1 瓦片空白或错位优先级最高的排查项我遇到的第一个坑是“加载出来的地图是歪的”明显看出道路和地名对不上或者某些区域花屏。这个问题的根源几乎全是坐标参考系不匹配。你用了vec_w的URL但OpenLayers视图是3857瓦片偏移就会非常明显。排查方法很简单打开浏览器开发者工具Network面板里筛选wmts请求看瓦片URL里的TILEMATRIXSET和View的projection是否成对。如果视图是3857但URL里是TILEMATRIXSETw直接把URL模板改成wm对应路径也改成vec_wm。另一种常见情况是“瓦片404”并且半天不显示。这通常是请求的缩放级别超出了天地图服务范围比如你强行设了zoom: 20但天地图这一层级还没有数据。解决办法是给View设置maxZoom: 18并在切换缩放时做兜底。4.2 并发请求过多被限流前面提到天地图的密钥有配额限制。实际表现是页面刚打开时一切正常拖几下地图之后部分瓦片开始返回429或403甚至整个地图都白了。我排查过这个现象常见原因是同一个页面上同时加载了太多天地图图层比如矢量底图、矢量注记、影像底图、影像注记四个图层同时保持visibletrue那么每次拖动地图可能产生几十上百个并发请求。解决的思路有三个不显示的图层一定设为visiblefalse。OpenLayers对不可见图层不会发请求这也是我们用图层组切换的另一个好处。多域名分散请求。把请求URL随机分布到t0到t7子域降低单域名QPS压力。OpenLayers的XYZ源支持urls数组直接把8个域名写进去即可。如果并发还是压不住可以用Nginx反向代理做天地图瓦片缓存把高频瓦片落到自己的服务器上。这个方案适合做大屏项目代价是维护成本变高一般项目不需要上。4.3 切换体验优化预热、缓存与最大缩放级别底图切换本身是瞬间完成的因为OpenLayers只是切换visible状态并没有销毁重建任何对象。但由于影像瓦片通常比矢量瓦片大第一次切换到影像时会出现一段“瓦片加载中”的白格子时期。要改善这个体验可以在浏览器空闲时把目标图层的瓦片提前缓存下来。我的做法是在页面初始化后把影像组的visible设为false的同时调用一次imageBaseLayer.getSource().setAttributions之类的方法并不实际更直接的方式是让Map在加载阶段先从影像模式渲染一次利用浏览器缓存再切回矢量模式。不过这个方案会白费一次加载流量不是所有项目都舍得。另一个折中办法是监听tileloadend事件在矢量模式下悄悄预取当前视野的影像瓦片到浏览器缓存用户点击切换时命中缓存的速度会快很多。代码大概长这样imageBaseLayer.getSource().on(tileloadend, function () { // 统计加载完成的瓦片数按需做预热进度提示 });实际测试下来预热能让影像切换至少快一倍。但要注意如果项目里瓦片量很大预热也可能把天地图的密钥配额吃撑所以预热范围最好限制在当前View的可见范围。另外切换操作不会影响Map的view中心点和缩放级别会原样保留所以“切换后地图飞走”这种问题一般不会出现。但要注意不同底图的最大缩放级别差异影像图的18级往往比矢量图清晰度高矢量图到了18级路网信息可能稀疏。我习惯在切换后做一次级别兜底如果当前zoom超过17就回退到17。5. 常见问题速查从现象到原因5.1 问题对照表下面这张表是我在这个项目里遇到的典型问题基本覆盖了90%的排查场景。现象常见原因解决办法地图完全空白容器高度为0检查#map的CSS高度地图空白Network显示403tk密钥错误或域名未加白名单检查控制台配置地图空白Network显示404TILEMATRIXSET或图层名拼写错误对照官网文档检查URL地图花屏、道路偏移视图投影与TILEMATRIXSET不匹配统一为EPSG:3857 wm有底图无地名注记缺少注记图层cva或cia叠加对应注记图层拖动地图后大量瓦片加载失败触发天地图限流隐藏不可见图层多子域轮询地图被业务图层遮挡zIndex顺序不对设置底图组zIndex为0业务图层zIndex≥10排查时最好先开Network直接看瓦片请求的状态码。返回200但页面没显示的查CSS和layer添加顺序返回403的查密钥和域名白名单返回404的查URL参数返回429的多半是被限流了。按这个顺序走一般不迷路。5.2 换一种框架代码怎么改很多人在社区里问“React/Vue里怎么用”其实核心逻辑完全不变区别只是生命周期挂载方式的差异。以Vue 3为例import { onMounted, onBeforeUnmount } from vue; import Map from ol/Map; import View from ol/View; import TileLayer from ol/layer/Tile; import Group from ol/layer/Group; import XYZ from ol/source/XYZ; let map; onMounted(() { const vectorLayer new TileLayer({ source: new XYZ({ url: tdtUrl(vec, wm) }) }); // 省略其他图层创建 map new Map({ target: map, layers: [vectorGroup, imageGroup], view: new View({ projection: EPSG:3857, center: [116.391, 39.907], zoom: 11 }) }); }); onBeforeUnmount(() { map.setTarget(undefined); map null; });注意在单页应用里组件卸载时一定要调用map.setTarget(undefined)释放地图实例否则会出现DOM残留。5.3 后续扩展思路这个项目的切换功能还可以扩展出很多玩法。首先是加地形底图。天地图也有地形底图服务图层名是ter注记是cta参数规则完全一致。你只要再加一个terrainGroup切换按钮支持三态就能让用户在矢量、影像、地形之间切换。我在另一个项目里就是这样做成多底图切换的。其次是叠加业务数据。天地图只负责做底图真正的业务数据要用OpenLayers的Vector图层叠加。比如业务人员上传的GeoJSON、GPS轨迹、围栏多边形都可以挂在独立图层上切换底图时业务数据始终保持不动。还有一个高频需求是天地图逆地理编码。天地图提供了服务端API可以在点击地图时反查出坐标对应的地名和地址把结果展示在弹窗里。这个和底图切换是两条独立链路但对业务系统来说经常是一起用的。如果你在桌面GIS里也需要类似底图QGIS同样支持直接添加天地图WMTS地址方法就是把上面这个URL粘贴到QGIS的WMS/WMTS连接里。开发环境可以先用QGIS验证一下图层和坐标参考系是否正常再回前端调代码能省不少排查时间。最后分享一个我个人的调试习惯永远先把关键信息打到控制台。我写这个功能的时候第一步不是渲染地图而是在控制台输出当前视图的投影、中心和缩放级别再输出四个图层的visible状态。确认状态无误再去看画面效果问题定位会快很多。还有一个小技巧在地址栏直接访问天地图瓦片URL如果浏览器能直接显示一张图片说明密钥和地址参数没问题可以排除服务端因素专注查前端代码。下一次遇到“地图白屏”不妨先按住F12看一眼Network。地图开发一半靠写一半靠查排查路径清晰了很多问题都是十分钟的事。