OpenLayers 与 Leaflet 加载天地图全系图层（矢量/影像/地形+底图/注记）——原理与实战

摘要：天地图作为国家地理信息公共服务平台，提供标准的 WMTS​ 瓦片服务。本文将深入解析天地图的双投影体系与图层分层设计原理，并分别给出 OpenLayers（XYZ/WMTS方式）​ 与 Leaflet​ 加载矢量底图、矢量注记、影像底图、影像注记、地形晕渲及地形注记的完整可运行代码，附带坐标系匹配、Key配置、注记叠加顺序等核心避坑指南。

一、天地图服务原理与图层体系解析

1.1 WMTS 服务与分层设计原理

天地图遵循 OGC WMTS（Web Map Tile Service）​ 标准，预先将地图切割为 256×256 像素的栅格瓦片。其核心设计特点是底图与注记分离：

• 底图图层：承载几何图形（道路、建筑、影像纹理），如 vec（矢量）、img（影像）、ter（地形晕渲）。

• 注记图层：透明背景的文字标注（地名、路名、POI），如 cva、cia、cta。

• 叠加逻辑：注记图层必须具有 透明度（PNG格式），且在渲染顺序上始终置于底图之上，否则文字会被底图遮盖。

1.2 双投影体系（核心坑点）

天地图 URL 中的后缀决定了坐标系，前端 View/CRS 必须严格匹配：

• _w 后缀（Web 墨卡托 EPSG:3857）：正方形投影，与 Google Maps、OSM、OpenLayers 默认投影一致，适合 Web 端展示。

• _c 后缀（经纬度 EPSG:4326）：单位为中文度，适合 GPS/CGCS2000 数据直接匹配。

⚠️ 严禁混用：EPSG:3857 的 View 不能加载 _c 的瓦片，否则会出现严重偏移。

1.3 常用图层类型对照表（以墨卡托 _w 为例）

地图类型

底图 Layer 标识

注记 Layer 标识

适用场景

服务地址模板：

https://t{0-7}.tianditu.gov.cn/{layer_type}/wmts?
SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&
LAYER={layer}&STYLE=default&TILEMATRIXSET=w&
FORMAT=tiles&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk={您的Key}

• t0-t7：天地图二级域名，用于并发负载均衡。

• TILEMATRIXSET=w：对应 EPSG:3857 切片矩阵集。

二、OpenLayers 加载天地图全系图层实战

OpenLayers 推荐使用 ol/source/XYZ​ 方式加载天地图（比原生 WMTS 配置更简单，内部自动处理分辨率矩阵），也可使用 TileWMTS。

2.1 环境引入

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v7.4.0/ol.css" />
<script src="https://cdn.jsdelivr.net/npm/ol@v7.4.0/dist/ol.js"></script>

2.2 封装通用图层创建函数（XYZ方式，EPSG:3857）

const TDT_KEY = '您申请的天地图Key'; // 必填，否则403

// 创建天地图XYZ图层
function createTDTLayer(layerType, proj = 'EPSG:3857') {
const matrixSet = proj === 'EPSG:3857' ? 'w' : 'c';
return new ol.layer.Tile({
source: new ol.source.XYZ({
url: `https://t{0-7}.tianditu.gov.cn/${layerType}_${matrixSet}/wmts?` +
`SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=${layerType}&` +
`STYLE=default&TILEMATRIXSET=${matrixSet}&FORMAT=tiles&` +
`TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk=${TDT_KEY}`,
projection: proj,
wrapX: true
})
});
}

2.3 完整案例：矢量+注记 / 影像+注记 / 地形+注记 切换

// 1. 矢量底图 + 矢量注记
const vecBase = createTDTLayer('vec');
const vecLabel = createTDTLayer('cva');

// 2. 影像底图 + 影像注记
const imgBase = createTDTLayer('img');
const imgLabel = createTDTLayer('cia');

// 3. 地形晕渲 + 地形注记
const terBase = createTDTLayer('ter');
const terLabel = createTDTLayer('cta');

// 初始化地图（默认显示影像底图，注记必须在底图之后addLayer）
const map = new ol.Map({
target: 'map',
layers: [imgBase, imgLabel], // 顺序：先底图，后注记
view: new ol.View({
center: ol.proj.fromLonLat([116.39, 39.9]),
zoom: 10,
projection: 'EPSG:3857'
})
});

/* 切换示例：切换到矢量地图
map.getLayers().clear();
map.addLayer(vecBase);
map.addLayer(vecLabel);
*/

原理补充：OpenLayers 的 TileGrid 对天地图 w 矩阵集（原点 -20037508.34,20037508.34）内置支持良好，XYZ 源的 {z}{x}{y} 会自动映射为 WMTS 的 TileMatrix/TileCol/TileRow。

三、Leaflet 加载天地图全系图层实战

Leaflet 默认使用 EPSG:3857（L.CRS.EPSG3857），加载 _w 系列图层最为便捷；若加载 _c 必须显式声明 crs: L.CRS.EPSG4326。

3.1 环境引入

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

3.2 完整案例：矢量/影像/地形及其注记

const TDT_KEY = '您申请的天地图Key';

// 通用天地图瓦片层（墨卡托_w）
function tdtLayer(layerType) {
return L.tileLayer(
`https://t{s}.tianditu.gov.cn/${layerType}_w/wmts?` +
`SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=${layerType}&` +
`STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&` +
`TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk=${TDT_KEY}`,
{
subdomains: ['0','1','2','3','4','5','6','7'], // 负载均衡
tileSize: 256,
zoomOffset: 0,
maxZoom: 18
}
);
}

// 创建图层组（底图+注记绑定在一起）
const vecGroup = L.layerGroup([tdtLayer('vec'), tdtLayer('cva')]);
const imgGroup = L.layerGroup([tdtLayer('img'), tdtLayer('cia')]);
const terGroup = L.layerGroup([tdtLayer('ter'), tdtLayer('cta')]);

// 初始化地图
const map = L.map('map', {
center: [39.9, 116.39],
zoom: 10,
crs: L.CRS.EPSG3857 // 默认即此，显式写出便于维护
});

// 默认添加影像底图组
imgGroup.addTo(map);

注意：Leaflet 的 {z}{x}{y} 对应 WMTS 的 TileMatrix/TileCol/TileRow，且 tileSize 必须为 256，天地图不支持 512 瓦片。

四、避坑总结（高频报错排查）

• 403 Forbidden：未携带 tk=Key 或 Key 未生效（申请后有 5~10 分钟延迟，且需勾选“地图API”权限）。

• 瓦片错位/漂移：

  • OpenLayers View 设了 EPSG:3857 却用了 vec_c 的 URL（应改为 vec_w）。

  • Leaflet 未声明 crs 却加载了 _c 图层（默认 3857 会算错行列号）。

• 注记消失：注记层被底图层覆盖，确保代码中先 add 底图，再 add 注记，或使用 layerGroup 管理顺序。

• 边缘空白（wrapX）：全球地图建议在 OpenLayers XYZ 源中开启 wrapX: true，Leaflet 默认支持横向循环。

• 混合坐标偏移：天地图是 CGCS2000（近似 WGS84），若叠加高德/腾讯（GCJ-02 火星坐标）数据会产生几百米偏移，需在前端做纠偏转换。

五、小结

• 天地图本质是 WMTS 标准瓦片，_w(3857) 与 _c(4326) 投影不可混用是第一位的原则。

• 底图 + 注记​ 必须成对加载且注记在上，才能看到完整的“有字的地图”。

• OpenLayers 用 source.XYZ 是最简洁稳定的方案；Leaflet 用 L.tileLayer 拼 WMTS 模板即可覆盖矢量、影像、地形全系图层。

• 生产环境务必处理好 Key 的白名单​ 与 t0-t7 子域负载均衡。

📌 参考文献：天地图官方 WMTS 说明、OpenLayers 官方文档、SuperMap iClient 技术手册及主流 GIS 社区实战总结。