OpenLayers加载天地图瓦片：从零搭建WebGIS底图实战

我一直觉得，WebGIS 入门最劝退的不是算法，也不是服务端切片，而是“底图从哪来”。以前帮某项目组做数据可视化时，第一版方案直接在页面里嵌入商业地图 JS API，开发确实快，但一进入业务评审就卡住了：坐标加密、资质要求、调用配额，每一项都要重新谈。后来我们把底图切到天地图，半小时就把地图拉起来了，也正是那次经历让我决定把“加载天地图”作为 WebGIS 实战练习的第一篇。

这篇内容聚焦一件事：用 OpenLayers 在前端页面里正确加载天地图瓦片。适合刚接触 WebGIS、会一点 HTML/CSS/JavaScript、想自己动手把地图跑起来的读者。全程不涉及复杂后端，跟着做就能看到地图出现在浏览器里，同时我会把最容易被忽略的坐标、密钥、协议细节一起讲清楚。

1. 底图选型：为什么这个练习从天地图开始

1.1 消费级地图 API 和 WebGIS 底图的差异

很多前端同学习惯用商业地图的 JS API，一个 script 标签加一段初始化代码，地图就有了。但在实际 WebGIS 项目里，这类方案往往不是首选，原因集中在三个方面。

第一是坐标体系。商业地图对外展示用的坐标普遍经过偏移处理，而你手里的业务数据——无论是 GPS 采集点、测绘成果还是第三方提供的 GeoJSON——大多基于公开标准坐标。两套坐标混在一起，点位会“漂移”到马路对面去。要修正就得写纠偏算法，而纠偏规则本身不公开，维护成本很高。

第二是服务形态。商业地图 JS API 通常只能通过它的脚本库调用，瓦片地址不透明，不便和自研图层、服务端数据灵活拼接。而天地图提供标准的 WMTS/REST 瓦片服务，任何支持 XYZ 规范的 Web 地图库都能直接消费，这为后续叠加业务图层留了很大空间。

第三是合规和配额。正规项目对地图服务的数据来源、版权、部署环境有明确要求，免费的消费级 API 不一定适用。天地图作为国家级互联网地图服务网站，提供的是权威、公开、稳定的瓦片数据源，对项目组来说省去了大量沟通成本。

当然，如果你只是做一次性展示页，商业地图 API 仍然很方便。但如果你想系统学习 WebGIS、做点能沉淀的业务功能，从天地图开始更合适。

1.2 坐标基准：一开始就要树立的意识

这一步必须提前讲，否则后面大概率出问题。地图瓦片在浏览器里显示时，采用的是 Web 墨卡托投影，也就是 EPSG:3857，这个坐标系把地球近似展开成一张平面图，适合做底图显示和缩放。

而天地图服务里，瓦片服务命名中带w的通常是 Web 墨卡托投影，带c的通常对应经纬度地理坐标系，具体以官方服务文档为准。加载时选哪个，直接影响瓦片能不能对齐、业务数据能不能叠上去。

简单理解：浏览器地图世界是“平面投影坐标”，业务数据通常是“经度纬度”，两者之间需要转换。OpenLayers 里ol.proj.fromLonLat()就是干这件事的，后面代码里会用到。现在你只需记住——不要拿着经纬度直接填到以 3857 为投影的地图中心点上，规范做法是先转坐标。

2. 动手前准备：密钥申请、服务地址与容易忽略的协议细节

2.1 申请应用密钥的完整流程

加载天地图瓦片不是把 URL 拼上去就能跑，需要先获得一个授权密钥，就是代码里常见的tk参数。

流程不复杂：打开天地图官网，注册账号进入开发者页面，创建应用后系统会分配一个应用密钥。创建应用时通常需要填写应用名称、类型等信息。个人学习用途和项目商用用途的配额不同，具体以官网当时公布的开发者规则为准。

这里提醒三点。

第一，密钥是和域名/应用绑定的，如果本地调试用file://协议直接打开 HTML，部分环境下请求会被拦或无效，建议用一个本地静态服务来跑，比如npx serve或 VS Code 的 Live Server 插件。第二，密钥不要硬编码到需要提交到公开仓库的业务代码里，后面我讲封装时会给出临时方案，但彻底解决要靠服务端代理。第三，官方文档里的服务地址模板会变，域名、路径、参数以“服务资源”页面展示的最新地址为准，不要凭记忆写死。

2.2 认识瓦片服务地址：WMTS 与 REST 的细节

天地图瓦片服务看起来是一串很长的 URL，拆开看就清晰了。以矢量底图服务为例，一个典型的请求参数包括：

可以看到，瓦片服务的本质就是“按照层级、行号、列号去请求一张图片”，这正是 XYZ 规范做的事。所以 OpenLayers 里用ol.source.XYZ就可以把天地图当作普通瓦片源加载，不需要手动维护复杂的 WMTS 网格。

如果你看到某个项目里写的是 WMTS 图层，也别慌，只是换了个更严格的瓦片网格定义方式，底层请求到的还是格式化的瓦片图片。

2.3 HTTPS 和跨域：浏览器控制台最容易暴露问题的地方

现在网页基本都是 HTTPS 环境。如果你的页面是 HTTPS，而瓦片请求地址写成了http://，浏览器会直接拦截混合内容，地图区域干干净净一片空白。所以服务地址务必使用 HTTPS。

跨域问题相对隐蔽。浏览器加载瓦片属于跨域资源请求，天地图服务通常允许跨域访问，但如果你在本地随便起服务，有些配置下还是会看到 CORS 报错。我遇到过一次，项目组内部网络代理拦截了带tk参数的请求响应头，瓦片加载失败，排查半天不是代码问题。

如果页面控制台出现“No 'Access-Control-Allow-Origin' header”之类的信息，不要立刻觉得是天地图服务的问题，先检查自己的页面是否走了代理、服务地址是否写错、密钥是否有效。具体排查链路我放在第 4 章，那儿全是实战教训。

3. 核心代码：用 OpenLayers 把天地图跑起来

3.1 最小可运行示例

先来一个能直接运行的版本，用 CDN 引入 OpenLayers，方便你在纯 HTML 文件里验证。

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>加载天地图</title> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/ol3/.../" /> <style> #map { width: 100%; height: 600px; } </style> </head> <body> <div id="map"></div> <script src="https://cdnjs.cloudflare.com/ajax/libs/ol3/.../ol.js"></script> <script> const tk = '你的密钥'; // 天地图矢量底图服务地址，域名与参数以官方服务页面最新文档为准 const vecUrl = 'https://tiles.tianditu.gov.cn/vec_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk=' + tk; const map = new ol.Map({ target: 'map', layers: [ new ol.layer.Tile({ source: new ol.source.XYZ({ url: vecUrl, wrapX: false }) }) ], view: new ol.View({ center: ol.proj.fromLonLat([104, 30]), zoom: 5 }) }); </script> </body> </html>

注意，上面 CDN 链接里的版本号我故意没写全，因为 OpenLayers 的 CDN 地址经常调整，请自行替换为当前正式版本。代码里fromLonLat([104, 30])是对经纬度坐标做投影转换，转换后才是 Web 墨卡托坐标，地图中心会落在示例坐标附近。

如果这一步顺利，你会在页面里看到一张能拖动、能缩放的矢量底图。这个时刻很重要，意味着“瓦片请求在哪里、HTML 结构里放什么”你已经掌握了。

3.2 关键参数说明：projection、tileGrid 与 wrapX

第一个容易迷惑的参数是projection。在上面的 XY.Z 示例里我没有显式设置，OpenLayers 默认认为 XYZ 瓦片基于 Web 墨卡托投影，这也是绝大多数在线瓦片服务的默认规则。如果你的瓦片服务是经纬度坐标的c矩阵集，那就要手动指定投影，否则瓦片会贴在错误的位置上。

第二个是tileGrid。严格讲，WMTS 和 XYZ 的瓦片原点、网格规则不完全一样。天地图的 Web 墨卡托瓦片服务使用起来和 XYZ 兼容，所以用ol.source.XYZ可以省去配置瓦片网格的麻烦。如果你后续接入别的 WMTS 服务，就需要根据服务文档配置tileGrid的原点、分辨率列表和瓦片尺寸。

第三个是wrapX。我习惯设为false，意思是地图横向平移时不要无限循环包裹。有些底图源允许跨越 180 度经线循环显示，但业务数据叠加时容易出现“明明在这个位置，瓦片却从另一侧跑出来”的错觉。练习阶段关闭它，减少干扰因素。

关于图层类型：建议只用ol.layer.Tile和ol.source.XYZ。没有特殊需求时不要嵌套TileWMS、WMTS这些更高层封装，那是 WMTS 官方服务才需要的。

3.3 从单层底图到完整地图：叠加注记层

矢量底图加载起来只是第一步。细看你会发现地图上没有任何地名、道路名，纯色块加线条，业务价值不大。天地图的服务里通常还有注记图层，专门提供地名、水系名、道路名等文字信息。

加载注记层的方式和底图几乎一样，只是把LAYER参数从vec改成注记图层对应的名称，服务地址换一套。代码结构上，可以把两层都放进layers数组，先放底图再放注记，这样注记自然显示在底图上方。

const cvaUrl = 'https://tiles.tianditu.gov.cn/cva_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=cva&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk=' + tk; const baseLayer = new ol.layer.Tile({ source: new ol.source.XYZ({ url: vecUrl, wrapX: false }) }); const annotLayer = new ol.layer.Tile({ source: new ol.source.XYZ({ url: cvaUrl, wrapX: false }) }); const map = new ol.Map({ target: 'map', layers: [baseLayer, annotLayer], view: new ol.View({ center: ol.proj.fromLonLat([104, 30]), zoom: 5 }) });

影像底图、地形晕渲等其他图层也遵循同样的模式，只要把服务资源和LAYER参数换掉即可。这一套逻辑吃透，以后加任何瓦片图层都会很快。

4. 运行时的三个麻烦：坐标错位、灰格子、配额失效

4.1 坐标错位：瓦片级地图为何“漂移”

症状表现：地图能加载，但业务点位的经纬度位置明显偏移，比如点在路东，底图显示在路西；或者底图本身看起来整屏“平移”了一段。

排查链路，按顺序来。

先确认业务数据的坐标系。如果是 GPS、测绘数据，大概率是标准经纬度，可以直接交给 OpenLayers 处理；如果数据本身有加偏，那就是数据侧问题，和底图无关。然后检查瓦片服务使用的TILEMATRIXSET参数是否和你的 view 投影匹配。天地图通常用w（Web 墨卡托）更省事。再检查 view 的 center：不要写[104, 30]，而要写ol.proj.fromLonLat([104, 30])，这是新手最常见的错误点。

有个反直觉的现象值得说：有时地图中心显示正确，但缩放到某一级后，点位开始偏移。这种通常不是坐标算错，而是瓦片层级对应的分辨率与业务数据比例尺不一致，需要检查数据自身有没有经过投影转换。

本质上，Web 地图是“数据在不同坐标系之间不断转换”的过程。你在浏览器看到的坐标，经过了一次从经纬度到投影坐标的换算。如果底图和数据用了不同基准，那么只要目标投影一致，转换一次就能对齐；否则怎么调都是各偏各的。

4.2 灰格子和模糊瓦片：跨域与网络请求的锅

症状表现：地图区域出现成片的灰色网格，页面放大时部分瓦片刷不出来，有时过几秒又自己恢复了。

不要直接怀疑天地图服务不稳定，先打开开发者工具 Network 面板，刷新页面，过滤tiles或wmts请求，看瓦片请求的响应状态。

常见的三种情况。

第一种是请求状态 403。大概率是tk参数无效，或密钥和请求域名不匹配。检查密钥是否复制完整，有没有多余空格，开发者后台的应用配置是否允许当前域名。

第二种是请求状态 200 但返回内容不是图片。按下响应预览可以看到有时返回的是 XML 错误提示，这种现象通常和配额、参数格式有关，注意看 XML 里的说明文字。

第三种是浏览器直接拦截。如果是 HTTP/HTTPS 混合内容，控制台会提示 blocked，这种情况把瓦片地址改成 HTTPS 即可。如果页面部署在非 HTTPS 的内网环境，也要检查瓦片服务是否允许从当前 origin 访问。

这里有个偷懒技巧：Network 面板里点一条瓦片请求，直接在新标签页打开它的完整 URL。如果单独打开能显示图片，说明问题出在页面侧的环境配置；如果单独打开也报错，直接检查 URL 参数和密钥。

4.3 配额与鉴权异常：key 失效不是玄学

症状表现：刚加载时地图正常，滚动缩放一会儿后瓦片开始大面积空白，控制台请求返回TILEOVERLIMIT之类的提示。

这就是配额或并发限制被触发了。每个开发者密钥在个人练习阶段的每日请求量和每秒并发数是有限的，地图连续拖动、快速缩放时，一瞬间会发出大量瓦片请求，很容易顶到上限。

这不是代码 bug，但决定了好习惯：练习时不要写全屏自动轮播的图层刷新逻辑，也不要在一个页面里重复初始化多个地图实例。如果只是做加载练习，控制缩放频率即可。

更规范的解法是中间加一层瓦片代理缓存，把常用层级的瓦片缓存到本地服务器，前端只请求自己的域名，这样既隐藏了密钥，也降低了源站配额压力。这个属于后续进阶内容，现阶段先把密钥配置和日常使用规范做好。

5. 从练习到工程模块：把地图组件收进项目里

5.1 模块化设计与配置管理

现在你已经能把天地图加载到页面里了，但代码还是“打开 HTML 就跑”的形态。如果放进真实项目，建议立刻做两件事：第一，把所有可配置参数抽离出来；第二，把地图初始化封装成一个独立方法。

比如可以建一个地图配置对象：

const mapConfig = { tk: '你的密钥', layers: [ { name: 'vec', url: 'https://tiles.tianditu.gov.cn/vec_w/wmts?...&tk=' + '你的密钥', visible: true }, { name: 'cva', url: 'https://tiles.tianditu.gov.cn/cva_w/wmts?...&tk=' + '你的密钥', visible: true } ], view: { center: [104, 30], zoom: 5 } }; function initMap(target) { const layers = mapConfig.layers.map(item => ( new ol.layer.Tile({ source: new ol.source.XYZ({ url: item.url, wrapX: false }), visible: item.visible }) )); return new ol.Map({ target, layers, view: new ol.View({ center: ol.proj.fromLonLat(mapConfig.view.center), zoom: mapConfig.view.zoom }) }); }

这样地图相关的 URL、层级、中心点都集中在配置里，以后切换影像底图或调整初始视角，不用改初始化逻辑。

但在把tk写进前端代码这件事上，我要提醒你：前端代码里的密钥一定会暴露给用户，任何人打开开发者工具都能看到。个人练习阶段无所谓，正式项目建议通过后端接口代理瓦片请求，把tk放在环境变量或服务端配置里。如果只是做内网可视化大屏，还要评估是否需要做请求转发。

5.2 面向后续练习的地图骨架

加载天地图虽然只是一个小功能，但它给你搭好了后续所有练习的地图骨架。有了这个骨架，你可以继续做这些事：

• 叠加 GeoJSON 图层，把业务点位渲染到地图上；
• 加矢量标注和弹窗，做点位详情展示；
• 接入轨迹回放，让地图动起来；
• 封装图层控制面板，让用户切换底图和注记；
• 结合绘图交互，在地图上画范围、量算面积。

我自己的体会是，做 WebGIS 第一步千万别贪多，先把底图加载这件事弄透——坐标、密钥、瓦片协议、图层叠加——后面每加一个功能，都是站在这个稳定底座上的自然延伸。等这章练习完全跑通，你可以试着在浏览器控制台里执行一些地图方法，获取当前中心点、缩放级别，看看地图对象到底暴露了哪些能力，这会比急着写复杂功能更有收益。

最后分享一个实操小技巧：调试时把view的初始 zoom 设小一点，比如 3 或 4，这样可以一次性请求大量瓦片，快速判断图层叠加顺序对不对、注记层是否透明、请求是否超限。等确认无误，再把视图调整到实际业务需要的缩放级别。