⏱ 4 步速查（跟着做即可，详细步骤见下文）：
- 申请 Key：登录天地图控制台 →「应用管理」→「创建新应用」，应用类型务必选「浏览器端」，复制生成的 Key
- 装插件（最省事）：插件管理器搜索 TianDiTu Tools 并安装，在插件设置里粘贴 Key，一键加载矢量/影像/地形底图
- 手动配置：浏览器面板右键「XYZ Tiles」→「新建连接」，粘贴本文瓦片 URL，引用站点（Referer）填
https://www.tianditu.gov.cn/ - 加载不出来：拒绝访问先查 Key 类型与 Referer；空白/重试错误按「Key → URL → 节点 → 配额」顺序排查（见第 5 节）
天地图是国家地理信息公共服务平台的官方在线地图服务，数据权威、国内访问稳定，是国内 GIS 项目的首选底图之一。但与 OpenStreetMap 不同，天地图官方要求所有 API 及服务调用申请开发许可（Key），并自 2020 版起实行调用配额管理，且应用类型有严格限制——这也是大量用户在 QGIS 里「加载不出来」「拒绝访问」的根源。本教程按「申请 Key → 插件加载 / 手动配置 → 报错排查」的顺序展开，报错排查章收录了社区高频报错的真实现象与修复步骤。QGIS 加载在线地图教程 已覆盖高德、Google、OSM 等多种底图的通用配置，本文专注天地图本身的 Key 申请与故障处理。
1. 在 QGIS 里用天地图的三种方式
| 方式 | 适合人群 | 特点 |
|---|---|---|
| TianDiTu Tools 插件 | 新手、不想手写 URL | 官方插件库收录，填一次 Key 即可一键加载多种底图，附带地名搜索 |
| XYZ Tiles 手动配置 | 需要精确控制图层组合 | 逐层添加矢量/影像/注记，配合 Referer 设置稳定性最好 |
| WMTS 服务连接 | 企业/多图层场景 | 标准 OGC 协议，可加载完整图层树，配置项较多 |
三种方式都依赖同一个前提：一个有效的天地图 Key。所以先从 Key 申请说起。
2. 申请天地图 Key：类型选错是第一大坑
天地图官方要求：所有 API 及服务接口调用都需要申请开发许可（Key），可在控制台免费注册申请，配额按账号类型管理。申请流程：
- 打开天地图官网
tianditu.gov.cn，用手机号注册并登录（个人注册即可，调用量大的单位可注册为单位用户并完成企业认证） - 进入控制台
console.tianditu.gov.cn，申请成为天地图开发者（个人开发者或企业开发者） - 在控制台「应用管理」中点击「创建新应用」，填写应用名称（随意，方便自己识别）、行业类别（如实选择）
- 应用类型选择「浏览器端」——这是关键，详见下方说明
- 提交后在应用列表中即可看到生成的 Key（即 URL 中的
tk参数值），复制保存
3. 方法一：TianDiTu Tools 插件（推荐新手）
TianDiTu Tools 是 QGIS 官方插件库收录的第三方插件（作者 liuxspro，各版本覆盖 QGIS 3.4 至 4.99 的不同区间），封装了天地图各类底图的配置，并实现了地名搜索等部分天地图 Web 服务 API：
- 打开「插件」→「管理和安装插件」，搜索
TianDiTu或tianditu - 找到「TianDiTu Tools」，点击「安装插件」
- 安装后在工具栏（或右键工具栏空白处勾选「Tianditu Tool 工具栏」）找到插件入口
- 在插件设置中粘贴你申请的 Key（0.4.0 及以上版本支持配置多个 Key）
- 点击「添加图层」，选择矢量底图 / 影像 / 地形晕渲等图源即可加载
插件的优势是零配置、图源齐全（还包含部分省级天地图资源），缺点是功能受插件更新节奏限制——遇到插件无法加载时，手动 XYZ 配置往往仍可用，两种方式建议都掌握。
4. 方法二：XYZ Tiles 手动配置（可精确控制每一层）
天地图的「底图」和「注记」是两个独立服务，需要分别添加后叠加。常用图层的瓦片服务参数：
| 图层 | 服务代码 | 说明 |
|---|---|---|
| 矢量底图 | vec_w | 道路、水系、行政区划等底图要素 |
| 矢量注记 | cva_w | 中文地名标注，需叠加在矢量底图上方 |
| 影像底图 | img_w | 卫星影像 |
| 影像注记 | cia_w | 影像上的中文标注，需叠加在影像上方 |
| 地形晕渲 | ter_w | 地形渲染底图 |
以影像底图 + 影像注记为例（将 你的KEY 替换为实际 Key）：
# 影像底图
https://t0.tianditu.gov.cn/img_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=img&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk=你的KEY
# 影像注记（叠加在影像上方，中文标注）
https://t0.tianditu.gov.cn/cia_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=cia&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk=你的KEY添加步骤：
- 在浏览器面板中右键「XYZ Tiles」→「新建连接」
- 名称填如「天地图影像」，URL 粘贴上面的地址
- 在「引用站点（Referer）」框填入
https://www.tianditu.gov.cn/——不少「拒绝访问」的问题就出在漏掉这一步 - 点击 OK 保存，双击连接加载底图；再按同样方法添加注记图层并置于上方
t0 可替换为 t1～t7。某个节点不稳定或速度慢时，换一个节点通常可以解决。带中文标注的完整效果 = 底图层 + 对应注记层叠加。
5. 报错实录：加载不出来 / 拒绝访问怎么排查
5.1 「瓦片请求最大重试错误」，底图一片空白
现象：图层已添加到图层面板，但地图画布空白，日志面板反复出现「瓦片请求最大重试错误」（Tile request max retry error）之类的网络错误。
按顺序检查四项：
- Key 是否填了、填对了：URL 末尾的
tk=参数必须是完整有效的 Key；网络流传的旧教程 URL 往往不带 tk，如今直接失效 - Key 类型是否为「浏览器端」：类型选错（如服务端）会持续请求失败（见第 2 节）
- 节点是否可用：把 URL 中的 t0 换成 t1～t7 其他节点测试；最快的验证方法是把替换好 {z}/{x}/{y} 具体数值（如 z=8、x=200、y=100）的 URL 直接粘到浏览器地址栏——浏览器能出图说明 Key 和网络都通，问题在 QGIS 侧配置
- 配额是否用尽：登录控制台查看「访问统计」，当日配额耗尽则等次日恢复，长期需求考虑企业认证或备用 Key
5.2 「拒绝访问」/ HTTP 403
现象：请求返回 403，地图无法加载。403 几乎都指向鉴权与防盗链：
- Referer 防盗链：天地图对瓦片请求校验来源。在 QGIS 的 XYZ 连接「引用站点（Referer）」中填入
https://www.tianditu.gov.cn/后重新加载，这是社区实测最有效的修复 - Key 无效或被禁用：在控制台确认 Key 状态正常；不放心就新建一个浏览器端 Key 替换测试
- 触发限额：超额后的请求同样会被拒绝，结合访问统计判断
5.3 有底图但没有中文注记
现象：影像或矢量加载正常，但地图上没有地名文字。
原因与修复：这不是故障——天地图的底图与注记本来就是两个独立服务。再按第 4 节的方法添加一层注记服务（矢量底图配 cva_w，影像配 cia_w），并在图层面板中把注记层拖到底图层上方即可。
5.4 地图位置偏移或图层叠加不上
现象：天地图能加载，但与自己叠加的矢量数据位置对不上，或瓦片整体偏移。
原因与修复：服务代码末尾的 _w 表示 Web 墨卡托投影（与网络地图通用坐标系一致），_c 表示经纬度直投版本。两者混用、或项目坐标系设置不当，都会造成偏移或叠加失败。常规用法：瓦片选 _w 系列，项目 CRS 按数据实际情况设置；另需注意，部分其他地图服务（如高德）使用 GCJ-02 坐标系，叠加时天生存在偏移，这不是天地图的问题。
5.5 加载缓慢或瓦片缺块
现象：瓦片一块一块慢慢出现，或局部永远加载不出来。
修复：更换节点（t0～t7）；在「设置」→「选项」→「网络」中降低最大并发连接数后再试；底图显示异常时清空瓦片缓存强制重新下载。需要反复浏览固定区域时，可在联网时提前浏览完成缓存，或把区域导出为 GeoTIFF 离线使用。