上周把vue3项目部署到线上服务器第二天同事就找过来“地图白屏了控制台一片403。”我看了一眼浏览器Network面板天地图的瓦片请求齐刷刷返回403 Forbidden。这个场景我太熟了本地开发时地图还好好的一上服务器就出问题十有八九是跨域、Referer、白名单这几件事没理清楚。这篇文章把我排查天地图403的完整思路和落地解法整理出来涵盖本地开发、服务器部署、Nginx反代几种典型场景最后还会给出一套推荐方案和速查表。如果你正好被天地图403折磨可以直接照着抄。1. 先搞清楚403的本质天地图API的鉴权机制1.1 浏览器端的Referer和Origin到底是什么要解决403先得理解浏览器是怎么携带身份信息的。天地图API的鉴权依赖两个关键HeaderReferer和Origin。Referer表示“我从哪个页面发起这个请求”。比如你在https://example.com/map页面里加载了天地图瓦片浏览器发给天地图的请求头里会自动带上Referer: https://example.com/map。Origin则类似但它更严格通常在跨域请求中才会出现而且只携带协议、域名、端口不包含具体路径。天地图服务端拿到这两个Header后会提取出里面的域名部分和你在天地图控制台里配置的白名单做比对。域名匹配就放行不匹配就返回403。这就解释了为什么同一个key在本地开发环境能用部署到服务器就报错——因为服务器的域名或IP压根没在白名单里。还有一个细节容易被忽略如果你通过IP地址访问项目浏览器发送的Referer里就是IP比如http://123.45.67.89:8080。这种情况下你必须把IP加进白名单而且天地图控制台对IP白名单的填写格式有要求我们后面细说。1.2 天地图403是哪种鉴权模式被触发我在实际排查中总结过天地图403基本就两种模式第一种是域名白名单模式。天地图key在申请时可以绑定域名列表只有Referer域名在列表里的请求才会被放行。这个模式适合纯前端调用浏览器直接访问天地图服务器。第二种是IP白名单模式。有些项目用服务端代理前端请求自己公司的后端接口后端再去调天地图。这种情况下天地图看到的是后端服务器的IP所以需要在控制台配置IP白名单。怎么区分当前项目触发的是哪种方法很简单打开浏览器控制台看失败请求的Request URL。如果请求地址是https://tiles.tianditu.gov.cn/...这种天地图官方域名说明是前端直连走域名白名单。如果请求地址是自己域名比如https://api.example.com/tianditu/...说明走了服务端代理需要查服务器的出口IP白名单。明白这个机制后排查思路就清晰了先确认请求路径再对照白名单类型逐项检查配置。2. 本地开发环境403的典型原因与排查2.1 最常见的白名单没配localhost很多人在天地图控制台创建key时只填了正式域名比如example.com开发时用http://localhost:5173访问项目请求发出去天地图一看Referer是localhost和配置的example.com不匹配直接403。解决起来不复杂在天地图控制台的域名白名单里把localhost和127.0.0.1都加进去。天地图控制台允许填写多个域名用逗号或换行分隔具体看控制台界面提示。但是这里有个坑我提醒过很多次localhost和127.0.0.1在referer里是两个不同的值。有些项目的开发服务器绑定的host是127.0.0.1浏览器访问的是http://127.0.0.1:5173那么Referer里的域名就是127.0.0.1。如果你只配了localhost照样403。所以稳妥做法是两个都加上。另外如果开发时用了--host 0.0.0.0让局域网其他设备访问那Referer就成了192.168.x.x这种局域网IP你还得把这个IP也加进去。否则手机访问就是403电脑访问没问题很多人会忽略这个场景。2.2 本地配置正确了为什么还是403还有一种情况白名单加好了刷新页面还是一堆403。这时候重点检查两件事第一浏览器缓存。天地图瓦片请求会被浏览器缓存。如果你之前访问过带有错误key或错误白名单的页面浏览器缓存里可能已经存了403响应。有些浏览器比如Chrome在缓存未过期前不会重新发请求。处理办法就是强制刷新CtrlShiftR或者打开无痕窗口测试。第二多个key混用。如果页面里引用了多个天地图key或者HTML模板里写死了一个失效的key即使控制台配置了正确的白名单也没用。检查方式是在Network面板里看具体请求的URL参数确认使用的是哪个tk参数。2.3 开发环境的推荐配置我现在开发vue3项目时通常直接配置两个环境变量# .env.development VITE_TIANDITU_KEY你的开发key VITE_TIANDITU_DOMAINhttp://localhost:5173 # .env.production VITE_TIANDITU_KEY你的生产key VITE_TIANDITU_DOMAINhttps://example.com开发和生产各用各的key白名单也是各配各的互不干扰。这样能避免“开发环境改了生产key上线前忘记换回来”的低级错误。我还会在代码里做一道校验防止引用错误的key// 在初始化天地图之前 const devKey import.meta.env.VITE_TIANDITU_KEY if (import.meta.env.DEV !devKey.startsWith(dev_)) { console.error(检测到开发环境使用了非开发key请检查.env.development) }这个校验代码很简单但能避免不少误操作。3. 部署到服务器后的403排查这是重灾区3.1 域名、IP、端口三者不匹配部署到服务器后最容易踩的坑就是线上的访问地址和天地图白名单里配置的地址不一致。举个例子你的正式域名是example.com配置了HTTPS证书访问地址是https://example.com。天地图白名单里也填了example.com。看起来没问题对吧但如果某个页面里用了http://example.com的资源或者通过http://IP:端口访问Referer就会变403就来了。还有一种情况服务器上有多个域名通过Nginx反代到同一个vue3项目。比如a.example.com和b.example.com都指向同一个项目但天地图白名单里只配了a.example.com。访问b.example.com时Referer是b.example.com自然403。排查这类问题我的习惯是在浏览器控制台执行document.referrer或者直接用curl模拟请求curl -I https://tiles.tianditu.gov.cn/v4.1/tile.wmts?servicewmtsrequestGetTileversion1.0.0LAYERimgtilematrixsetwStyledefaultFormattilestilematrix1tilerow0tilecol0tk你的key \ -H Referer: https://example.com返回200就说明Referer和key匹配返回403就说明还是没配对。这个方法能快速定位问题。3.2 Nginx反代导致Referer丢失或变化如果你用Nginx反代策略还把天地图的API地址也一并反代了那要特别注意Nginx默认行为。Nginx在默认配置下会把请求头发送给上游服务器但如果你用了proxy_set_header Referer或者proxy_pass方式改变了请求地址Referer可能被覆盖或丢失。举个例子你的Nginx配置里写了location /tianditu/ { proxy_pass https://tiles.tianditu.gov.cn/; }浏览器请求https://example.com/tianditu/tile.wmts?...Nginx转发给天地图时Referer变成了https://example.com/tianditu/tile.wmts这个域名如果不在白名单里照样403。更麻烦的是有些Nginx配置会把Referer头直接删掉location / { proxy_set_header Referer ; }这种配置常见于大型门户网站的反代层目的是防止被判定为防盗链。如果你把天地图请求也走了这个代理那天地图收到的Referer就是空字符串白名单肯定匹配不上403几乎必然发生。解决这个问题的方案有两种要么不让Nginx代理天地图让浏览器直连天地图官方域名走域名白名单要么在Nginx里显式设置Referer为允许的域名。我更推荐前者能少一层中间环节减少出错点。3.3 服务器时区、时间不同步会导致签名类403天地图部分高级接口比如地理编码或路径分析要求请求里带上timestamp参数并做签名。这种signature类型的key在鉴权时会校验时间和实际时间的误差范围通常允许5分钟左右的偏差。如果服务器的时间没有用NTP同步或时区设置错了签名验证就会失败返回403。这类403和Referer无关你把域名白名单配得再全也没用。排查方法是在服务器上执行date -R然后和本地时间比较差值超过5分钟基本就是这个问题。解决办法是同步时间# Ubuntu/Debian sudo timedatectl set-ntp true # CentOS/RHEL sudo ntpdate ntp.aliyun.com设置完后再次执行date -R确认时间恢复正常。这一步应纳入服务器初始化清单。3.4 HTTPS和HTTP混用带来的Referer异常还有一些项目站点本身是HTTPS但页面里部分资源用的是HTTP链接导致浏览器在发送Referer时会因为安全策略降级或者直接丢弃场景。Chrome有一条规则从HTTPS页面发起请求到HTTP地址时Referer策略会收紧在某些情况下不发送Referer或将Referer降级为仅携带origin。如果天地图的请求被代理到了HTTP地址就可能收不到完整的Referer白名单校验就会失败。排查方法也很简单看浏览器控制台里天地图请求的Referer到底发了什么。如果发现是空的或者只有https://example.com但没有后续路径就要检查页面里是否有HTTP资源引用或者Nginx是否做了HTTP到HTTPS的跳转导致请求链路中Referer被截断。4. 双管齐下前端适配与后端代理的落地方案4.1 前端加载天地图脚本的方式vue3项目中引入天地图SDK常规做法是在index.html里加script标签script srchttps://api.tianditu.gov.cn/api?v4.0tk你的key/script但如果你是SPA应用而且可能切换不同环境我更推荐在runtime阶段动态加载// src/utils/tianditu.ts export function loadTiandituScript(key: string): Promisevoid { return new Promise((resolve, reject) { const scriptId tianditu-sdk const existing document.getElementById(scriptId) if (existing) { existing.remove() } const script document.createElement(script) script.id scriptId script.src https://api.tianditu.gov.cn/api?v4.0tk${key} script.onload function () { resolve() } script.onerror function (e) { reject(new Error(天地图SDK加载失败)) } document.head.appendChild(script) }) }为什么建议动态加载因为这样可以在切换路由或重新登录后方便地替换key或强制刷新SDK。缺点是如果SDK加载本身因为403导致失败这时代码层面的错误捕获能力就有限了——你需要额外监听script.onerror并给出用户友好的提示。然后初始化地图import { loadTiandituScript } from /utils/tianditu const key import.meta.env.VITE_TIANDITU_KEY await loadTiandituScript(key) // 确保window.T存在 const map new window.T.Map(map-container, { center: new window.T.LngLat(116.39, 39.9), zoom: 12 })这种写法配合Vite的环境变量可以做到不同环境零改动。我在生产环境里用这套方案跑了很久稳定可靠。4.2 最稳的方案服务端代理彻底绕开前端跨域如果你的项目对安全性要求高或者前端直连天地图时总是出现各种环境差异导致的403我推荐你改成服务端代理方式。原理很简单前端请求自己的后端后端再去请求天地图。天地图的白名单配的是后端服务器的IP前端完全不用关心Referer和key。以Nginx为例在server块里加一个location# 天地图瓦片代理 location /tianditu/ { proxy_pass https://tiles.tianditu.gov.cn/; proxy_set_header Host tiles.tianditu.gov.cn; proxy_set_header Referer https://tiles.tianditu.gov.cn/; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_ssl_server_name on; proxy_ssl_name tiles.tianditu.gov.cn; proxy_connect_timeout 10s; proxy_timeout 30s; }这里的关键是第三条proxy_set_header Referer https://tiles.tianditu.gov.cn/;把Referer固定为天地图官方域名无论前端请求从哪里来后端都是这个Referer天地图那边永远不会因为Referer不匹配而403。前端不再直接加载天地图SDK的script而是把瓦片请求地址指向自己的域名// 把天地图底图地址替换为代理地址 const layer new window.T.TileLayer({ getTileUrl: function (tileCol: number, tileRow: number, tileLevel: number) { return https://example.com/tianditu/tile.wmts?servicewmtsrequestGetTileversion1.0.0LAYERimgtilematrixsetwStyledefaultFormattilestilematrix${tileLevel}tilerow${tileRow}tilecol${tileCol}tk${key} }, projection: new window.T.MercatorProjection() })服务端代理的好处有三点key不暴露给前端白名单只需要配一次服务器IP无论用户从哪里访问行为都一致。缺点是服务器带宽和Nginx的处理能力会成为瓶颈高并发时瓦片请求量大需要留意带宽成本。所以这个方案更适合用户量可控的项目。4.3 结合两种方案的推荐架构我实际落地时通常这样设计开发环境前端直连天地图走域名白名单生产环境前端直连天地图走域名白名单同时Nginx层只对天地图做缓存不代理请求这个架构的关键是生产环境不要做请求代理但是要做瓦片缓存。Nginx可以缓存瓦片响应减少对天地图的重复请求量location /tiles/ { proxy_pass https://tiles.tianditu.gov.cn/; proxy_cache tianditu_cache; proxy_cache_valid 200 24h; proxy_cache_key $uri$is_args$args; add_header X-Proxy-Cache $upstream_cache_status; }如果公司对安全要求很高再单独用服务端代理方案。两种方案不要混在一起用否则排查起来很痛苦。5. 天地图坐标拾取、底图不显示等衍生问题5.1 坐标拾取工具怎么避免403项目里经常有这个需求地图上点击某个点弹出该点的经纬度坐标。如果你把坐标拾取功能直接放在前端每次点击都去调用天地图的服务接口比如https://api.tianditu.gov.cn/geocoder那这个接口同样需要鉴权同样会有403风险。我的实践经验是坐标拾取的功能尽量本地化。天地图客户端SDK本身就有右键拾取坐标的能力直接在事件回调里拿坐标即可不需要额外调用服务端接口map.addEventListener(click, function (e) { const lngLat e.lnglat console.log(选中坐标:, lngLat.getLng(), lngLat.getLat()) })这种纯前端的坐标拾取不会触发服务端鉴权也就没有403的问题。如果业务必须调用天地图的地理编码服务地址转坐标或坐标转地址那我建议走服务端代理把/geocoder接口代理到后端避免前端直接访问天地图API。这样白名单统一配服务器IP前端只要关心业务逻辑。5.2 底图不显示不只是403的问题很多人在ArcGIS、QGIS里加载天地图底图时遇到“不显示”的问题第一反应是403但其实403只是其中一种情况。如果你在ArcGIS里添加天地图WMTS服务控制面板会提示“无法添加图层”或者添加后黑屏无数据。这个时候看网络请求如果返回403那就是白名单问题。如果返回200但地图依然空白那有可能是坐标系或图幅范围设置不对。天地图WMTS用的是CGCS2000坐标系在ArcGIS里加载时需要设置正确的空间参考。ArcMap和Pro对WMTS的图层刷新方式不同有时候需要手动缩放到天地图支持的层级范围比如1到18级超出层级范围自然空白和403无关。QGIS加载天地图时一般推荐用XYZ瓦片方式而不是WMTS因为QGIS对WMTS的缓存策略有时会导致图层不刷新。但这个“不刷新”和403完全不同不要混为一谈。5.3 Vue3组件里使用天地图需要注意的事vue3里用天地图特别容易踩生命周期坑。天地图SDK管理的是DOM节点如果你用Vue的条件渲染v-if控制地图容器容器被销毁重建后地图实例还指向旧的DOM就会出现“地图容器存在但地图不显示”的诡异现象。这跟403没关系但如果排查时同时遇到403两个问题叠加在一起会让你误判为同一个原因。我的约定是地图实例的生命周期和页面组件严格同步。组件挂载后创建地图卸载前销毁地图onMounted(async () { await ensureTiandituLoaded(key) map new window.T.Map(map-container, {...}) }) onBeforeUnmount(() { map null const container document.getElementById(map-container) container.innerHTML })这样能避免大部分“地图不显示”问题也能让我们更专注地去排查403相关的网络请求。另外如果项目里同时用了ECharts和天地图需要把ECharts实例绑定到地图容器之外的一个DOM上不能共用同一个div否则地图事件和图表渲染会互相干扰。6. 常见问题速查表与避坑清单6.1 常用排查命令和工具我把排查403时用到的工具整理成一张表方便你对照使用场景工具/命令操作方式查看请求Referer浏览器开发者工具 Network 面板点击失败请求查看 Headers 里的 Referer模拟不同Referer请求curl -H Referer: https://example.com在本地自定义Referer测试白名单是否生效检查服务端转发头Nginx access.log查看实际发送给上游服务器的Referer值检查服务器时间date -R对比本地时间差值超过5分钟需同步检查服务器出口IPcurl ifconfig.me对比天地图控制台里的IP白名单检查同一域名下多个keyF12 搜索tk参数确认页面上所有请求使用的是同一个有效key6.2 403场景对照表错误场景可能原因解决路径本地开发403白名单没配localhost/127.0.0.1控制台补充白名单两个域名都加本地开发403局域网访问白名单没配局域网IP将本机局域网IP加入白名单部署后403域名访问白名单没配正式域名控制台添加正式域名等待生效部署后403IP访问白名单没配服务器IP将服务器公网IP加入白名单Nginx代理后403Referer被改写或清空修改Nginx配置固定Referer为合法值HTTPS/HTTP混合403Referer策略收紧统一使用HTTPS避免HTTP资源引用二次开发接口403时间不同步导致签名失败同步服务器时间校准时区更换key后403使用了旧key或缓存了旧key清浏览器缓存或强制刷新6.3 我踩过的三个隐性坑第一个坑是天地图控制台配置白名单后的生效延迟。我之前改完白名单刷新浏览器立刻测试发现还是403。原因不是配置错了而是CDN层面的缓存还没过期等了差不多两分钟再测就好了。所以不要改完配置立刻下结论先等一分钟再验证。第二个坑是Nginx的proxy_pass路径末尾斜杠。如果proxy_pass https://tiles.tianditu.gov.cn;末尾不带斜杠Nginx会把完整的原始URI附加到上游域名后面如果带斜杠会替换掉location匹配的部分。这两种写法对天地图瓦片URL的参数解析有影响。天地图瓦片URL本来是/v4.1/tile.wmts?servicewmts...你在代理的时候要保持这个路径不变不然天地图返回的参数解析失败表面看是403实际上是404或参数错误。排查时要看仔细。第三个坑是开发环境的代理工具。很多vue3项目用Vite的server.proxy做开发代理这个代理默认会把Referer和Origin改写成目标域名所以你在vite.config.ts里代理天地图时如果把路径配置错了请求发不到天地图官方域名就会在开发时出现各种奇怪的403。解决方式是在server.proxy里单独处理天地图路径不要把所有请求一股脑交给一个通用代理。6.4 最终推荐的项目接入方式我结合这几个月的项目经验把推荐的接入流程整理如下第一在天地图控制台申请两个key一个开发用一个生产用。开发key的白名单配localhost、127.0.0.1、本机局域网IP生产key的白名单配正式域名或服务器IP。第二vue3项目用环境变量区分key确保代码里不出现硬编码。第三生产环境优先使用纯前端直连配合Nginx层缓存瓦片。如果业务涉及服务端调用比如地理编码再单独配置服务端代理。第四部署后第一件事先用curl测试天地图接口的Referer匹配情况确认无误再让测试人员介入。这个流程完成后天地图403基本不会复现。我后来接手过几个类似项目用这套流程排查最慢的一次也没超过半小时就定位到了问题根源。天地图403虽然报错很干脆但背后的原因其实很集中大部分都是白名单和Referer没对齐。把这套排查思路和解决方案掌握好再遇到这个问题就能直接对症下药不用每次都在网上搜半天。