MapLibre GL JS 如何加载天地图底图
在 MapLibre GL JS 中加载天地图底图,核心是申请浏览器端 Key,再用 raster 源配置带 tk 参数的瓦片 URL(推荐 DataServer 或 WMTS 格式,配合 t0–t7 子域名),并强制设置 tileSize 为 256。通过 style 对象或 addSource/addLayer 叠加矢量/影像底图与对应注记层即可,默认使用球面墨卡托(_w)图层以匹配 MapLibre 的 EPSG:3857。截至 2026 年 11 月,MapLibre GL JS 最新版本为 6.16.0,安装后直接按下方步骤即可跑通。

申请 Key 与准备开发环境
天地图所有瓦片请求都必须带有效 tk,否则返回 401。先到国家地理信息公共服务平台注册并实名,创建应用时选择“浏览器端”,填写域名白名单(本地测试可暂时留空,上线后填完整域名)。个人账号有配额限制,具体次数以控制台显示为准,可申请多个 Key 轮换。申请流程与 Leaflet 场景基本一致,可直接参考本站Leaflet 加载天地图与 Key 申请教程,按同样步骤拿到浏览器端 Key 后替换到 URL 即可。
环境准备推荐两种方式:npm 安装 maplibre-gl(当前稳定版 6.16.0),然后引入 JS 与 CSS;或直接用 CDN 的 ESM 模块。v6 起为 ESM-only,注意正确设置 worker。项目里再准备一个空 div 作为地图容器,并保证页面有足够高度。
- npm:npm install maplibre-gl,再 import { Map } from ‘maplibre-gl’; import ‘maplibre-gl/dist/maplibre-gl.css’;
- CDN:引入 unpkg 上对应版本的 css 与 .mjs,用 import * as maplibregl from ‘…’
- 官方源码与示例可到 MapLibre GL JS GitHub 仓库 查看最新提交与 issues
加载天地图的完整操作步骤
下面以矢量底图(vec_w)+ 矢量注记(cva_w)为例,给出可直接复制改造的流程。影像底图只需把图层名换成 img_w / cia_w。
- 定义 Key 常量,并生成 8 个子域名的 tiles 数组,避免单域名限流。
- 写一个 style 对象:version 设为 8,sources 里添加两个 type 为 raster 的源,tiles 使用 DataServer 模板,显式写 tileSize: 256、maxzoom: 18,并加上 attribution。
- 在 layers 数组里按顺序添加两个 raster 图层(先底图后注记),保证注记盖在底图上面。
- 实例化 Map:传入 container、style、center(如 [116.4, 39.9])、zoom(建议 10–12),并设置 maxZoom 不超过 18。
- 打开浏览器控制台,确认 Network 里瓦片请求状态为 200,画面清晰无偏移,即验收通过。
DataServer URL 模板示例(把 YOUR_KEY 换成真实 tk):
https://t0.tianditu.gov.cn/DataServer?T=vec_w&x={x}&y={y}&l={z}&tk=YOUR_KEY(t1 到 t7 同理)。WMTS 格式也可,把 SERVICE、LAYER、TILEMATRIX 等参数拼完整即可。两种格式 MapLibre 都支持,社区实践中 DataServer 更简洁。

常用图层类型与关键配置参数
天地图 Web 墨卡托(_w)图层适合直接叠在 MapLibre 默认投影上,坐标系为 CGCS2000,与 WGS84 差异通常在亚米级,日常叠加自有点线数据基本无感。下表列出最常用的几组:
| 图层用途 | 底图代码 | 注记代码 | 建议 maxzoom | 说明 |
|---|---|---|---|---|
| 矢量电子地图 | vec_w | cva_w | 18 | 日常底图首选,道路与行政区清晰 |
| 影像底图 | img_w | cia_w | 18 | 卫星影像 + 道路注记 |
| 地形晕渲 | ter_w | cta_w | 14 | 山地场景,级别不宜过高 |
raster source 必填/常用字段:
- type: ‘raster’
- tiles: 字符串数组(至少放 t0–t7 共 8 个 URL)
- tileSize: 256(默认 512 会导致模糊,必须改)
- maxzoom: 与实际服务匹配(矢量/影像 18,地形约 14)
- attribution: ‘© 天地图’(建议保留)
- scheme: ‘xyz’(默认即可)
若使用第三方控件 maplibre-gl-basemap-control,可直接传 tiandituApiKey,它内部已封装好上述 URL 与叠加逻辑,适合快速切换底图。
注意事项、常见报错与验收标准
动手前先确认这几件事,能少走很多弯路:
- Key 类型必须是浏览器端,且正式环境域名白名单要写全;测试阶段可空,但上线后务必补齐。
- tileSize 漏写 256 是最常见“模糊”原因;maxzoom 设太高会出现空白瓦片,设成实际值后允许 MapLibre overzoom。
- CORS:天地图多数情况下可直接被 fetch,若本地出现 Failed to fetch,可临时用自家服务器做反向代理并加 Access-Control-Allow-Origin。
- 海外访问延迟较高,服务器在中国大陆更稳;配额超限时到控制台查看或换 Key。
- 旧 .com 域名已不可用,一律使用 .gov.cn。
验收标准很简单:地图中心定位正确、缩放至 16–18 级仍有清晰瓦片、注记不遮挡关键要素、控制台无 401/404、切换底图/注记无闪烁。满足这些即可认为加载成功。
常见问题
为什么瓦片全部空白或只有部分区域有图?
多数是 Key 无效、白名单不匹配,或 zoom 超出服务实际级别。检查 URL 末尾是否带正确 tk,把 source 的 maxzoom 降到 18(地形 14),并确认使用了 t0–t7 轮询。
地图看起来发糊,怎么处理?
几乎都是 tileSize 没设成 256。MapLibre 默认按 512 处理,会把 256 瓦片拉伸。加上 tileSize: 256 后刷新即可恢复锐利。
注记层和底图对不齐或偏移明显怎么办?
确认两边都用 _w(墨卡托)而不是 _c,并且 center/zoom 一致。CGCS2000 与 WGS84 差异很小,若仍感觉偏移,优先检查自有数据的坐标系是否也是 WGS84/CGCS2000。
本地开发正常,部署到服务器后瓦片加载失败?
检查控制台里的域名白名单是否包含正式域名,以及 HTTPS 混合内容问题。必要时把 Key 换成服务器端类型并用后端代理转发,避免前端暴露完整 Key。
总结:MapLibre GL JS 加载天地图就是“申请浏览器端 Key + raster 源 + tileSize 256 + 底图注记双层叠加”。优先用 DataServer 模板和 t0–t7 数组,把 maxzoom 卡在实际可用级别。建议先按本文步骤跑通矢量底图,再扩展影像或地形;Key 申请细节可随时回看本站Leaflet 加载天地图与 Key 申请教程。按验收标准自测一遍,就能稳定用在正式项目里。