做GIS开发这几年每年都会收到不少“天地图Token怎么注册”的私信。明明官网示例代码里只要拼一个tk参数很多人却卡在第一步找不到申请入口就算进了控制台也不知道该填什么。今天我把从注册、申请到实际配置的完整流程拆开讲一遍顺便把那些文档里不会写明白的坑也一并列出来。这篇文章适合刚接触Web GIS前端开发的朋友也适合准备在ArcGIS、Leaflet、小程序里接入天地图底图的同学看完至少能少走两小时弯路。1. 为什么非要一个Token1.1 Token不是玄学是门禁卡先给完全没接触过的朋友解释一下Token到底是什么东西。你可以把天地图的地图服务想象成一个小区的公共设施Token就是小区单元门的门禁卡。你没有卡就进不了楼物业也不会知道谁在楼里做了什么。天地图平台通过每个请求上携带的Token知道是谁在调用调了多少次符不符合配额然后决定给不给你返回瓦片数据。所以Token不是一个抽象的“验证码”而是一把实实在在的钥匙。它在天地图接口里的参数名统一叫tk你申请到的那个32位左右的字符串就是它的值。很多教程里把Token和API Key、密钥混着叫其实用到天地图这里都是指同一个东西。1.2 不申请Token能直接用吗不能。你如果拿网上搜到的某个瓦片地址不加Token直接访问返回的结果就是403或者一段XML错误告诉你没有访问权限。有些老示例代码里的tk12345678901234567890123456789012是官方文档里的演示值自己项目里直接复制大概率也是“Invalid Token”。我见过不少学生项目最早用的是别人泄露的Token先不说这种行为不安全光是“用着用着突然挂掉”就够受的。因为天地图对每个应用Key都有每日请求配额一个Key被太多人用很快就会超限。最稳妥的做法是注册一个自己的账号申请免费的个人开发者Token。很多人问有没有“免费token”其实就是这一步实名认证后创建的应用本身就是免费基础版足以支撑个人学习和小流量的项目。1.3 天地图Token和JWT登录Token不是一回事这里要特别提醒一句网上搜“token续签”“token失效”会出来一大堆关于JWT、OAuth的内容很容易把新手带偏。天地图的Token本质上是API密钥是静态字符串你把它固定在请求URL里即可没有过期时间也不需要像JWT那样频繁刷新。如果你的项目本身有登录功能使用了Access Token Refresh Token方案那是另一个体系。天地图Token好不好使和你系统的登录Token有没有过期没有任何关系。把这两件事分开能少踩很多坑。后面我会专门讲“续签”的问题这里先有一个基本概念天地图的key不会因为时间自然失效更多是因为你改了配置或者超了配额。2. 完整注册流程从账号到Key2.1 注册账号与开发者实名认证第一步当然是要有一个天地图账号。用电脑浏览器打开天地图官方网站右上角能看到注册入口手机号、邮箱都可以注册。这一步很常规没什么特别要说的关键是注册完之后别急着去复制链接第一步先完成开发者认证。流程是这样登录后进入“开发资源”或者“控制台”页面系统会提示你进行开发者认证。个人开发者需要填写姓名、证件号码、联系方式等真实信息。有朋友觉得麻烦随便填了一个手机号符号结果后续审核不通过应用一直创建不了白白浪费时间。认证审核一般是几分钟到几个工作日状态变成“已认证”之后再进行下一步。我个人的习惯是注册完就直接把账号密码放进密码管理器之后重置Key、查看用量都要登录。天地图不像普通论坛账号那样可以随便找回绑定邮箱和手机都要真实可用。这一点听起来像废话但确实有人因为注册邮箱填错了后续控制台登录不上只能找客服申诉流程拖很久。2.2 创建应用应用类型和域名白名单这一步是重点很多人第一次创建应用看着表单一头雾水。登录控制台后找到“应用管理”点击“创建应用”。需要填写的主要内容有三块应用名称随你起比如“我的地图项目2025”方便自己识别就行。应用类型有个人学习、企业开发、政务应用等选项。这里建议按实际情况选个人学习/个人开发者的审核最简单如果给公司做内部系统就选企业相关选项因为后续可能要上传营业执照。白名单这是最关键的配置项。如果创建的是浏览器端应用需要填写允许访问的域名如果是服务端应用则需要填写服务器IP地址。创建完成后应用列表里就会出现一串Key这就是你需要的Token。先别急着关页面点击复制然后找个工具做一次联调验证。2.3 用一次真实请求验证Token是否可用验证Token是否生效最快的方法是直接用浏览器访问一个带tk参数的瓦片地址。比如天地图影像底图的WMTS地址是这样的https://t0.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimgSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX3TILEROW1TILECOL3tk你的Key把这个地址粘贴到浏览器地址栏回车后如果能正常显示一张正方形图片说明Token没问题请求链路也通了。如果返回的是XML错误或403大概率是白名单没配上。这里要特别提醒一下白名单规则你的域名如果带端口通常也需要写上完整的来源地址。本地开发的时候我个人建议把localhost和127.0.0.1都加上因为很多场景下浏览器拿到的Referer是http://localhost:8080但如果你用http://127.0.0.1:8080调试又会被另一个域名规则挡住。两个都写上能省不少无谓的排查时间。提示天地图的在线服务通常有多个子域名常见是t0、t1、t2、t3它们是同一个服务的不同负载节点。搭建代码时可以随机轮询也可以固定使用t0请求前先确认自己申请的应用类型支持浏览器端还是服务端。3. Token在常见场景里的配置方法3.1 Web网页加载Leaflet 天地图在Web端最常见的做法是用Leaflet或者OpenLayers加载瓦片图层。以Leaflet为例你需要在瓦片URL里拼接tk参数。一个可以直接跑起来的最小示例是const token 你的Key; const tiandituImg L.tileLayer( https://t0.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimgSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk${token} ); const tiandituCia L.tileLayer( https://t0.tianditu.gov.cn/cia_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERciaSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk${token} ); const map L.map(map).setView([39.908, 116.397], 10); tiandituImg.addTo(map); tiandituCia.addTo(map);这里我用了img_w影像底图和cia_w影像注记两层这样能看到地图上的道路名、地名。矢量图对应的是vec_w和cva_w。需要注意参数里TILEMATRIXSETw代表Web墨卡托投影如果你需要经纬度坐标的切片对应的值通常是c。用错投影参数会出现地图错位、标注飘移检查半天往往发现是这里出了问题。代码里如果把Token直接写在JavaScript文件里意味着任何看过你前端代码的人都能拿到这个Key。如果是个人学习项目倒无所谓但生产环境我建议在服务端做一层代理Token放在环境变量里页面请求代理接口由代理转发给天地图。道理和你在浏览器里不直接暴露数据库密码是一样的。3.2 ArcMap / ArcGIS Pro 加载在线天地图很多从ArcGIS转到在线底图的朋友习惯用ArcGIS的WMTS服务连接方式。ArcGIS Pro里可以在“插入”菜单下找到“连接”选择“新建WMTS服务器”然后把带Token的WMTS地址粘贴进去。ArcMap则是在Catalog窗口中展开“GIS服务器”选择“添加WMTS服务器”。这里有个坑天地图的WMTS地址中同时包含了符这在部分版本ArcGIS里解析会有问题。表现为“无法读取服务器元数据”或者“XML格式无效”。解决办法是不要手动一个字一个字地敲URL直接复制完整地址而且注意地址中不要漏掉tk后面的Key。加载进图层后如果发现底图位置偏移优先确认你是否选择了正确的坐标系。如果只是需要在ArcGIS里快速叠加一张影像底图也可以直接使用天地图官方提供的ArcGIS插件或者在线服务地址。不过插件版本更新往往赶不上平台参数调整遇到白屏先检查Token是否有效这个原则是通用的。ArcGIS Pro对WMTS兼容性比ArcMap好一些如果你有选择我建议用Pro来测试。3.3 小程序 / App 端Token放置的思路微信小程序或原生App里加载天地图很多人会踩同一个坑小程序有域名白名单校验而且对于外部图片、外部请求的域名限制很严格。直接把https://t0.tianditu.gov.cn塞进request合法域名有时候能过有时候会被拦截。稳妥一点的做法是用WebView加载本地HTML页面然后在页面里用Leaflet加载天地图这样能绕开小程序对图片域名的一些限制。不过如果一张一张瓦片走小程序的wx.request会非常慢而且Token直接暴露在小程序包里非常容易被别人抓包盗用。所以我更推荐的服务端代理方案是把Token放在你自己的业务后端小程序请求/proxy/tianditu这个接口后端收到后加上Token再请求天地图最后把图片流返回给前端。这样做既隐藏了Token也方便你在服务端做缓存、日志流量统计。很多工具类小程序、GIS类App都是这么处理的虽然多一跳但对安全性的提升非常明显。4. Token失效、用量与“续期”的那些坑4.1 什么情况会导致Token突然失效我自己遇过一次很典型的场景上午项目还好好的下午所有瓦片突然变成灰块。控制台一查Token状态正常配额也没超最后发现是浏览器里加载页面的域名变了——原来测试用的http://localhost:8080后来换到局域网IP访问白名单里没有这个IP对应的域名规则。常见失效原因可以整理成一个稳定的排查清单域名白名单没包含当前访问域名尤其是带端口、带IP地址的访问源。浏览器端Key和服务端Key被混用一个限制Referer一个限制IP。应用下的Token被重置导致旧Token立即失效。免费配额当天耗尽接口开始拒绝返回瓦片。应用因为违规调用被平台自动封禁。如果你遇到的报错信息里有“Invalid Token”先别怀疑平台打开浏览器的“网络”面板看看实际请求URL上的tk值是不是你当前应用最新的Key再看白名单配置。这一步能过滤掉80%的问题。4.2 如何查看Token用量和配额天地图的控制台里可以查看每个应用的“当日调用量”“本月累计调用量”等信息。具体入口可能在“应用管理”或者“统计信息”里不同时期页面改版后位置略有不同核心思路是找到当前应用的详情页里面会列出该应用明确定义的服务配额。一个典型的免费个人应用每天有几十万次的瓦片请求配额个人学习一般用不完但高并发业务不一定够用。我建议在项目上线前先用统计工具记录几天内真实瓦片请求量估算出日均QPS。比如一个地图大屏用户每切换一个区域前端会请求大量瓦片几个大屏同时开着配额消耗速度远超你想象。如果后台显示该应用“已欠费”或“配额不足”说明免费额度被用完了。这时候要么升级套餐要么优化自己的缓存策略。一定不要“借用”网上别人公开的Token因为对方一旦重置Key你项目里的所有地图都会瞬间失效而且这种行为本身也容易被平台封禁。4.3 Token需不需要“续签”怎么处理才安全前面说过天地图的Token不是JWT不会因为“过期时间到了”而失效。但如果项目里你自己维护了一套登录体系热词里总出现“jwt实现token续签”那是另一回事——你自己的access token过期后用refresh_token换新的和天地图Key没有关系。所以不要给天地图Key写定时刷新脚本。不过为了安全我还是建议定期重置Key比如每季度一次。控制台点击重置之后旧Key会立即失效这一步操作看起来简单但如果应用正在线上跑重置后所有用户都会加载不出地图。正确做法是先在控制台创建一个新应用拿到新Key后配置到服务端确认新Key工作正常再把线上请求切到新Key最后在控制台删除或停用旧应用。这样就能做到无缝切换。5. 常见问题与排查方法5.1 页面瓦片加载失败单独访问却正常这种是最常见的“代码问题”不是Token问题。单独浏览器能打开说明Token有效白名单也覆盖了当前页面问题出在代码拼URL的方式上。常见错误包括Template字符串写错、{z}被转义、Token中混入了空格、或者把Token放在了HTTP请求头而不是URL参数里而天地图WMTS请求要求的是tkURL参数。排查时建议打开浏览器开发者工具找到加载失败的那个瓦片请求直接复制请求地址到新标签页打开。如果新标签页能显示图片说明是代码拼接问题如果新标签页也报错再回到Token和白名单排查。这个方法简单有效能快速定位是前端问题还是服务端问题。5.2 返回403 Forbidden但Token刚申请403通常有两个大方向一是访问来源不符合白名单这台服务器或这个页面的域名没有被加入允许列表。二是配额为0或者IP被平台临时限流。这时候登录控制台看应用状态再确认当前请求的Referer或IP地址是否真的在白名单内。尤其当你用服务器代理去访问天地图时要确认白名单里放的是服务器出网IP不是本机IP也不是用户端IP。另外如果你所在网络环境下无法正常打开天地图官网或在线服务接口通常说明当前网络到天地图服务的链路存在问题这是网络层面的限制换一个Token也解决不了。可以先确认是否能通过浏览器访问带Key的瓦片地址能访问说明链路没有问题。5.3 Token疑似被盗刷怎么办如果后台显示调用量暴增或者发现某个曾经发布过的前端页面一直有人访问但你的项目压根没对外开放那Token很可能已经在不知情的情况下被爬取了。处理方法比较简单第一时间在控制台重置Key旧Key立刻失效。然后把影响范围控制在最小给后端服务单独绑定IP白名单给前端页面绑定严格的域名白名单不要让一个Key同时拥有“浏览器端”和“服务端”的全部能力。顺带说一句天地图官网有一个“坐标拾取”工具很多人以为它也需要消耗Token其实不是。那是官方提供的一个交互页面你可以在上面点选坐标、查看经纬度完全不需要Token。但如果你在自己的项目里实现了类似的坐标拾取功能底图是天地图那毫无疑问也要用Token。两者不要搞混。6. 一点关于日常使用的个人经验最后讲几个我在实际项目中沉淀下来的习惯。首先任何环境变量都不建议写死在仓库代码里尤其是一份能看到Key的前端代码。把Token放到服务端环境变量或者配置中心不但安全后续切换Key也不需要重新发布前端。其次申请完Key之后我建议先用浏览器验证一次再写代码这样后续所有报错都至少能排除“Token本身有问题”这个因素。另一个常被忽略的点是不同环境用不同Key。开发环境、测试环境、生产环境各申请一把白名单范围从小到大严格配置这样即使开发Key泄露了也不会影响生产。生产Key被重置的时候开发环境还能照常联调不至于所有环境同时断掉。如果你还是第一次接触天地图建议先拿一个简单页面把影像底图加上再慢慢尝试叠加注记、搜索POI和坐标拾取。地图服务这种东西跑通一次最基础的链路剩下都是熟能生巧。我踩过的这些坑希望你在实际使用中能一次绕过去。