场景QGIS 里挂天地图底图图层加成功了瓦片也在刷画面却是一片灰每个格子上写着此级别下该区域无影像。打开浏览器 F12 一看状态码 200图片也确实回来了。这时候大多数人会往配额上想——毕竟天地图个人 key 有每日调用量。我踩过的结论是200 的灰图和配额没关系它是层级参数名写错了。四种返回码把校验顺序摆出来天地图前面挡了一道华为云 CloudWAF校验是分层的返回码正好暴露了先后顺序。2026-10-13 我在本机用 curl 复跑前两行不带任何有效 key 就能验证请求情况状态码返回内容URL 里不带tk418CloudWAF 的 HTML 页标题「访问被拦截」tk是乱填的一串403{code:301001,msg:非法key,resolve:请到API控制台重新申请Key}tk合法但 User-Agent 与 key 类型不匹配403{code:301013,msg:权限类型错误}全部正确200真实瓦片图片前两行我换过浏览器 UA、补过 Referer 头返回内容一字未变说明 key 的有无与合法性这两关与 User-Agent 无关。第三行的 301013 只在 key 合法时才轮到那是下篇的主题。顺带一句418 本身是个非标准状态码RFC 里它是彩蛋用途这里被 WAF 当作拦截标记使用。复现命令任何人都能跑# 不带 tk → 418 拦截页 curl -s -o - -w \nhttp%{http_code}\n \ https://t0.tianditu.gov.cn/DataServer?Timg_wx170y512l10 # 乱填 tk → 403 301001 curl -s -o - -w \nhttp%{http_code}\n \ https://t0.tianditu.gov.cn/DataServer?Timg_wx170y512l10tk00000000000000000000000000000000灰图的真正原因l写成了z天地图的 XYZ 地址模板官方长这样https://t0.tianditu.gov.cn/DataServer?Timg_wx{x}y{y}l{z}tk你的key层级参数是l{z}等号左边那个小写字母l小写 L等号右边才是 QGIS 的占位符{z}。网上流传的模板里常把它写成z{z}。服务端读不到l参数就按默认逻辑取一个当前图层根本没有的层级于是回你一张 HTTP 200 的占位灰图。这就是假成功——状态码全无异常请求也确实拿到了图片只是那张图片的内容是此级别下该区域无影像。改法只有一处- https://t0.tianditu.gov.cn/DataServer?Timg_wx{x}y{y}z{z}tk你的key https://t0.tianditu.gov.cn/DataServer?Timg_wx{x}y{y}l{z}tk你的key在 QGIS 里改的位置是Browser 面板 → XYZ Tiles → 双击对应连接 → URL 那一栏。改完不用重启重新加载图层即可。图层代号别写错T后面是图层代号四个img_w影像vec_w矢量cia_w影像注记cva_w矢量注记注记就是单独一层文字标注。底图和注记是两条瓦片地址要挂两个图层叠起来只挂img_w是没有地名的。如果你走的是 WMTS 标准入口参数名不一样LAYER后面写的是img/vec/cia/cva不带_w层级参数也叫TILEMATRIX而不是l。两套模板混着抄最容易出错这也是灰图的第二个来源。WMTS 完整模板https://t0.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimgSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk你的key还有一个前提坐标系别调错天地图瓦片是 CGCS2000和 WGS84 的差异小于 10cm日常当同一套用没问题。但工程 CRS 如果设成了 Web 墨卡托EPSG:3857以外的自定义投影瓦片会重投影看起来像位置不对而不是加载失败别和本文这两类问题混在一起排查。小结看到 200 的灰图先查参数名l和图层代号看到 418 或 301001查 key 本身看到 403 的301013 权限类型错误那是 User-Agent 和 key 类型对不上解法在下一篇《QGIS 加载天地图 403 权限类型错误User-Agent 分流与三种解法》。测试环境 QGIS 3.40.1Windows返回码复现时间 2026-10-13。