QGIS连接天地图最新指南：搞定Token和Header，解决加载失败问题
天地图作为国内权威的地理信息服务，在QGIS中的集成使用一直是GIS从业者的高频需求。但最近不少用户反馈，按照网上流传的旧教程配置后，天地图服务在QGIS中无法正常加载，地图显示空白或报错。这背后往往是API接口更新导致的认证机制变化——特别是Token验证和请求头(Header)配置这两个关键环节。
本文将深入解析2023年天地图API的最新调用规范，手把手教你排查和解决连接失败问题。不同于基础操作指南，我们更聚焦于那些"按照教程操作却无法使用"的典型场景，帮你彻底理解天地图服务在QGIS中的集成原理。
1. 天地图服务连接失败的常见原因
最近半年，天地图官方对API接口进行了多次安全升级，导致许多旧教程中的配置方法失效。根据社区反馈和实际测试，连接失败主要集中在这几个方面：
- Token验证失败：表现为地图空白或提示"无效的token"
- 请求头缺失：特别是缺少
sec-ch-ua等浏览器标识头 - URL格式错误：使用了已停用的旧版域名或参数格式
- 图层组合不当：影像与注记图层叠加顺序错误
注意：天地图不同服务类型（影像、矢量、注记）使用的域名可能不同，这是许多用户容易忽略的细节。
下表对比了新旧版天地图API的主要差异：
| 配置项 | 旧版API | 新版API要求 |
|---|---|---|
| 域名 | t0-t5.tianditu.com | t0-t5.tianditu.gov.cn |
| Token位置 | URL参数tk | URL参数tk |
| 必选Header | 无 | sec-ch-ua |
| 矢量图URL | vec_w | vec_w |
| 影像图URL | img_w | img_w |
2. 获取并配置有效的天地图Token
Token是天地图服务的身份凭证，获取方式如下：
- 访问天地图开放平台注册开发者账号
- 进入"我的应用"创建新应用
- 在应用详情中复制分配的Token密钥
常见Token相关错误及解决方法：
错误提示"INVALID_USER_KEY"
- 检查Token是否复制完整
- 确认Token所属应用的服务权限已开通
错误提示"TOKEN_EXPIRED"
- 企业认证用户Token有效期为1年
- 个人开发者Token有效期为3个月
# 测试Token是否有效的Python代码示例 import requests token = "您的天地图Token" url = f"https://t5.tianditu.gov.cn/DataServer?T=img_w&x=100&y=50&l=10&tk={token}" response = requests.get(url) print(response.status_code) # 200表示Token有效3. 正确配置请求头(Header)参数
新版天地图API强制要求特定的浏览器标识头，这是许多连接失败的根源。在QGIS中配置Header的完整步骤：
在QGIS的Browser面板中右键"XYZ Tiles"
选择"New Connection..."
填写名称（如"天地图影像"）
输入正确的URL格式：
https://t5.tianditu.gov.cn/DataServer?T=img_w&x={x}&y={y}&l={z}&tk=您的Token点击"Authentication"选项卡
选择"API Header"类型
添加以下Header键值对：
Key Value sec-ch-ua "Chromium";v="110", "Not A Brand";v="24"
提示：Header值需要随浏览器版本更新而调整，当前配置适用于Chrome 110+版本。
4. 不同图层的URL配置差异
天地图提供多种服务类型，每种都有特定的URL格式。以下是2023年最新可用的URL模板：
影像地图：
https://t[0-5].tianditu.gov.cn/DataServer?T=img_w&x={x}&y={y}&l={z}&tk=您的Token影像注记：
https://t[0-5].tianditu.gov.cn/DataServer?T=cia_w&x={x}&y={y}&l={z}&tk=您的Token矢量地图：
https://t[0-5].tianditu.gov.cn/DataServer?T=vec_w&x={x}&y={y}&l={z}&tk=您的Token矢量注记：
https://t[0-5].tianditu.gov.cn/DataServer?T=cva_w&x={x}&y={y}&l={z}&tk=您的Token
关键细节：
t[0-5]表示可以使用t0到t5中任意一个子域名- 影像和矢量服务建议使用同一数字的子域名（如都用t3）
- 注记图层必须与基础图层配合使用
5. 系统化的故障排查流程
当天地图服务无法加载时，建议按照以下步骤排查：
检查网络连接
- 尝试在浏览器中直接访问天地图URL
- 确保没有网络代理干扰
验证Token有效性
- 在浏览器中构造含Token的测试URL
- 观察返回状态码和内容
审查Header配置
- 确保
sec-ch-ua头与当前浏览器版本匹配 - 可以在Chrome开发者工具的Network标签中查看实际请求头
- 确保
测试不同子域名
- 依次尝试t0到t5的不同子域名
- 某些子域名可能在特定网络环境下响应更快
检查图层叠加顺序
- 注记图层应放在基础图层之上
- 在QGIS图层面板中拖动调整顺序
# 使用curl测试天地图服务的命令行示例 curl -H 'sec-ch-ua: "Chromium";v="110"' \ "https://t3.tianditu.gov.cn/DataServer?T=img_w&x=100&y=50&l=10&tk=您的Token"6. 性能优化与最佳实践
除了解决连接问题，这些技巧可以提升天地图在QGIS中的使用体验：
- 缓存策略：在QGIS设置中增大瓦片缓存大小
- 并行请求：调整QGIS网络设置中的并行连接数
- 智能缩放：根据视图范围动态调整请求的缩放级别
- 混合使用：将天地图作为底图，叠加本地高精度数据
推荐配置参数：
| 参数项 | 建议值 | 说明 |
|---|---|---|
| 缓存大小 | 500MB | 减少重复请求 |
| 并行连接数 | 8 | 提升加载速度 |
| 最大缩放级别 | 18 | 平衡细节与性能 |
| 重试次数 | 3 | 应对网络波动 |
在实际项目中，我发现将天地图影像与OpenStreetMap道路数据叠加使用效果特别好。这种组合既能利用天地图的高质量影像，又能补充更详细的道路信息。
