做GIS开发或者经常在Web项目里接在线底图的朋友应该对“天地图”不陌生。它是国内面向公众提供在线地图服务的平台提供矢量底图、影像底图、地形晕渲、地理编码、逆地理编码等能力对国内项目来说最大的好处是访问稳定、数据覆盖好能直接作为底图服务使用。真正开始用之前绕不开的一步就是注册天地图Token。这个Token说白了就是你调用天地图各项服务的身份凭证没有它接口请求基本都会被拒之门外。我最早接触天地图的时候也以为“注册Token”就是注册个账号拿个Key结果被应用类型、白名单、服务地址这些名词来回折腾了好几轮。这篇就完整写一遍从注册账号、实名认证、创建应用、拿到Token再到三种常见调用方式的全过程顺便把Token失效、请求401、配额不够这些高频问题一起梳理清楚给准备接入天地图的同学做一份能直接照着操作的参考。1. 搞懂Token之前天地图能做什么为什么必须要Token1.1 天地图平台的基础能力天地图本质上是“国家地理信息公共服务平台”面向开发者和公众开放的在线地图服务体系。普通用户可以在网页上看地图、查点位开发者则可以通过官方提供的API把地图能力嵌入到自己的系统里。常见的能力包括在线底图瓦片矢量地图、影像地图、地形晕渲、全球境界线等都是按瓦片方式提供可以接入Web GIS框架也能接入桌面GIS软件。地理编码与逆地理编码输入“北京市朝阳区”之类的地名文本返回经纬度坐标输入经纬度返回地址描述。路径规划与距离测量支持驾车、步行、骑行等路线规划。搜索服务POI检索、周边搜索等。底图瓦片是多数人使用最多的功能因为做地图应用时最容易缺的就是一套稳定、可商用、数据源可靠的底图。天地图正好补上这个空缺而且在国内环境里访问速度通常不错不需要额外做复杂的网络适配。1.2 Token在天地图体系里扮演什么角色Token在天地图的API体系里就是一个字符串形式的密钥通常也叫Key。你需要在请求的URL参数或请求头里带上它服务端才能确认“这个请求来自一个合法注册的开发者”从而正常返回数据。用一个生活化的类比来说Token相当于小区门禁卡。你有这张卡才能刷卡进楼没有卡或者卡被注销了就只能被拦在门外。天地图服务端对所有未携带Token的请求默认视为身份不明直接拒绝返回数据。所以不管你只是做一次底图加载测试还是要开发一个完整的GIS系统Token都是必经环节。很多刚接触的人容易把“Token”和“用户账号密码”混为一谈。账号密码是你的登录凭证用来进管理后台Token则更接近“API专用子密钥”可以单独创建、单独禁用也可以限制在某个域名或IP环境下使用比拿着一套账号密码到处传要安全得多。1.3 免费额度与基本使用边界天地图对个人开发者有免费使用的政策具体算力和配额额度、每日请求量上限官方会根据不同认证等级和当时政策动态调整以你登录控制台后看到的额度为准。对于学习、原型验证以及中小型项目来说这个免费额度通常是够用的。需要留意的是天地图的Key是有应用场景区分的。你在申请Token时通常可以创建“浏览器端”类型的Key和“服务端”类型的Key两种Key的配额策略和校验机制不太一样。这一点非常重要后面我会单独用一节来细说因为很多401和Token失效问题十有八九是Key类型用错了地方。2. 注册天地图开发者账号第一步操作全流程2.1 注册前需要准备什么注册过程本身不复杂但建议先把手头资料备齐免得中途卡在实名认证环节。注册时需要准备的是一个常用的手机号用于接收验证码。一个能正常收信的邮箱注册后需要验证邮箱激活账号。个人实名认证的话需要本人姓名和身份证号如果页面触发人脸核验还要准备能配合扫码或拍摄的手机。如果是企业开发者提前准备好营业执照照片、统一社会信用代码等信息。这些材料都是平台注册的标配要求提前准备好整个注册流程最快十几分钟就能完成如果临时找证件反而会拖慢节奏。2.2 官网注册的具体操作步骤打开天地图官网也就是 tianditu.gov.cn在首页右上角会看到“注册”入口。整个过程按下面几步走点击右上角“注册”进入账号注册页面。按表单填写用户名、手机号、邮箱设置登录密码。密码要求通常包含字母、数字和特殊字符具体以页面提示为准。获取短信验证码并填写勾选阅读并同意相关服务条款。提交注册后系统会给你的邮箱发送一封激活邮件点击邮件里的链接完成邮箱验证。回到官网用刚注册的账号登录。这里有一个容易忽略的点邮箱验证必须做。有些朋友注册完直接登录控制台发现很多权限打不开回头检查才发现是邮箱没激活。账号激活后继续完善个人资料进入开发者中心就能看到后续的实名认证入口。2.3 实名认证与开发者类型选择在正式创建应用之前天地图会要求开发者完成实名认证。这一步避不开因为地图服务涉及在线内容发布与合规管理实名认证是所有在线地图服务商都在执行的统一规范。进入开发者中心后找到“开发者认证”或类似入口选择“个人认证”或“企业认证”。个人认证通常需要填写姓名和身份证号按要求完成人脸识别企业认证则额外需要营业执照、企业名称、统一社会信用代码等法人信息。认证材料提交后快的话几分钟内就能审核通过慢的话可能需要等待一两个工作日。对个人学习、技术研究来说个人认证已经足够使用。如果以后要做正式的商业项目再考虑升级为企业开发者到时候额度策略和可用的服务范围也会更完整。先认证个人项目推进中再渐进式调整是成本最低的路径。3. 创建应用并申请Token拿到那把“钥匙”3.1 进入控制台创建第一个应用完成实名认证后登录天地图官网进入“控制台”或“开发者中心”找到“应用管理”模块。创建一个新应用需要填写的基本信息包括应用名称建议用一眼能看懂的标识比如“地图底图测试应用”或“XX项目WebGIS”。应用类型通常区分“个人应用”和“企业应用”按你的认证身份选择即可。应用描述简单说明用途比如“用于XX系统在线底图加载”方便日后管理。提交后系统会自动为这个应用生成对应的Token/Key。你不需要手动输入任何密钥等系统生成就好。3.2 浏览器端Key与服务端Key的区别这是新手最常踩坑的地方。天地图同一个应用下通常会有两类KeyKey类型使用场景特点安全要求浏览器端Key前端HTML/JavaScript中请求瓦片或API可以直接写在网页请求参数里域名白名单机制限制来源会被公开暴露必须配置域名白名单防盗用服务端Key后端服务中调用天地图API请求不经过浏览器可以配置IP白名单不要泄露在前端代码里建议只在服务端保存在实际开发中最容易犯的错误是把浏览器端Key拿去做服务端代理请求或者反过来在浏览器直接调用服务端Key。天地图服务端只认Key的授权场景场景不匹配就会返回无权限或401。提示如果项目架构是“前端页面 后端代理”最稳妥的做法是前端用浏览器端Key并配置好域名白名单后端调用地理编码等服务时使用独立创建的服务端Key各司其职。3.3 配置域名白名单和IP白名单在应用详情页里你可以针对浏览器端Key设置域名白名单。这个白名单的作用是限制“哪些网页域名下可以使用这个Key发起请求”从源头降低Key被偷去刷量的风险。配置域名白名单时要注意几个细节写域名时不要随意省略。如果前端页面部署在https://map.example.com白名单里就要填写https://map.example.com不要只写example.com否则不同子域名或协议下可能匹配失败。如果页面同时通过HTTP和HTTPS访问测试环境下可能需要分别配置对应协议的目标域名。多个域名之间一般用英文分号隔开具体分隔符以控制台页面提示为准。本地开发时如果需要测试通常需要把http://localhost:端口号或http://127.0.0.1:端口号也加进白名单否则本地调试时会一直报无权限。服务端Key则没有域名白名单的概念通常可以使用IP白名单限制服务器出口IP也可以留空不做限制但生产环境建议配置避免Key泄露后被人随便调用。3.4 拿到Token后的安全自查创建完成后把Token复制到本地记录表之前先检查三件事确认你是否区分了浏览器端Key和服务端Key不要只复制一个。确认测试环境的域名/端口已经加入浏览器端Key白名单。确认你登录后看到的“服务端Key”没有被复制进前端代码仓库。Token在天地图体系里不会像JWT那样自动过期并靠refresh_token续期它主要是一个长期有效的身份凭证。如果官方控制台重置了密钥、应用被停用、或者Key到期失效才会导致已有Token不可用。也就是说不存在“拿到Token后每隔几小时要刷新一次”的机制日常维护中更需要注意的是别把Key泄露出去以及定期查看控制台用量统计。4. 拿到Token后怎么用三种常见调用方式4.1 方式一在网页底图中加载天地图瓦片天地图的在线底图瓦片服务支持WMTS和XYZ瓦片格式。以最常见的“矢量底图矢量注记”为例瓦片请求URL结构大致是https://t0.tianditu.gov.cn/vec_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk你的天地图Token其中vec_w表示全球矢量底图如果你想加载影像底图通常使用img_w矢量注记层一般是cva_w影像注记层是cia_w。{z}对应缩放级别经度方向瓦片编号由TILECOL控制纬度方向瓦片编号由TILEROW控制。tk参数就是你的Token是请求中必不可少的参数。如果你在前端集成OpenLayers、Leaflet或Mapbox这类地图框架一般要做的就是按框架要求配置XYZ或WMTS数据源把瓦片地址模板填进去。Leaflet的典型写法示例L.tileLayer( https://t0.tianditu.gov.cn/vec_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk你的天地图Token, { maxZoom: 18, attribution: 天地图, } ).addTo(map);在HTML页面里直接打开这个瓦片地址拼好的页面时确保域名在浏览器端Key的白名单内否则动态拼接的瓦片请求会大批量返回403或401一个底图格子都出不来。4.2 方式二在服务端调用地理编码或逆地理编码接口除了底图地理编码接口也很常用。天地图官方提供地理编码API可以输入结构化地址返回坐标也可以输入经纬度返回地址描述。在Python服务端调用时一个简洁的示例是import requests url https://api.tianditu.gov.cn/geocoder params { ds: {keyWord:北京市朝阳区}, tk: 你的服务端Token, } resp requests.get(url, paramsparams, timeout10) print(resp.status_code) print(resp.text)这里有几个关键点tk参数同样是身份凭证但建议使用服务端Token尤其当你在生产环境后端脚本里做批量地理编码时。ds参数是天地图GeoQuery服务要求的JSON字符串不同时期的接口细节可能稍有调整建议以官方文档为准来构造请求体。批量调用时要密切关注控制台的配额统计因为地理编码和底图瓦片通常共享配额或分别限额量大的时候容易触发“请求过于频繁”或“额度耗尽”。4.3 方式三在ArcGIS或QGIS桌面软件里加载天地图做GIS数据处理时桌面软件里加载天地图作为参考底图也很常见。ArcGIS和QGIS接入天地图的原理本质是访问WMTS服务只是具体入口不一样。在QGIS中可以通过“XYZ Tiles”方式添加天地图把上面的瓦片URL模板填入数据源对话框{z}、{y}、{x}由软件自动替换。在ArcGIS中则可以添加WMTS服务器输入天地图的WMTS服务地址并在服务参数里带上tk你的Token。有些版本会要求你先构建自定义图层文件再接入在线服务步骤会多一点但核心仍然是“服务地址参数正确 Token正确传递”。还需要特别提醒一下坐标系统的问题。天地图的在线切片底图基于CGCS2000坐标系也就是EPSG:4490而国外常用在线底图多是Web墨卡托EPSG:3857。在ArcGIS里直接叠加时最好明确项目的坐标系设置或者让GIS软件自动做动态投影否则很可能会看到底图与数据位置对不上看起来像是偏了几百米甚至几公里。这种情况不是Token的问题而是坐标系没有对齐。5. Token失效、配额不足与常见报错排查实战5.1 常见报错速查表实际操作中最常遇到的返回结果就是HTTP 401、403或者页面直接不加载瓦片。我整理了一个速查表基本覆盖日常高频问题。现象可能原因排查与解决思路页面请求瓦片返回401Token缺失、Token错误、Key类型用错确认URL参数名是否为tkKey是否正确复制确认浏览器端Key是否被用于非浏览器场景请求返回403域名白名单未配置或配置错误检查前端访问域名的协议、端口是否与白名单完全一致本地调试记得加localhost服务端调用报无权限服务端Key被浏览器端场景使用或IP白名单范围内不在在控制台重新创建服务端Key确认请求来自服务器出口IP不要在前端代码里传服务端Key瓦片偶尔加载不出过一会儿恢复请求频率超过单IP或单Key限制查看控制台用量统计降低并发数检查是否有循环请求导致刷量地图整体白屏浏览器控制台报错底图URL格式错误、图层名写错确认LAYER参数是vec/img/cva/cia等有效值确认TILEMATRIXSET与坐标系匹配底图出现偏移坐标系不匹配确认项目坐标系与天地图CGCS2000一致或在GIS软件里做动态投影5.2 “token exchange failed”这类报错是什么情况在网上搜索天地图Token问题时很可能会搜出一堆“token exchange failed”“sign-in could not be completed”之类的报错日志。需要明确提醒大家这些报错绝大多数来自GitHub、JetBrains等工具的OAuth登录流程和天地图没有直接关系。我见到过不少朋友被这些搜索结果带偏思路以为是自己的天地图Token没过期或续签逻辑有问题实际上两套机制完全不同。天地图的Token是按官方策略生成的长效密钥没有“登录交换”的步骤也不会报“token exchange failed”。如果你遇到的报错文案里带着“login server”“refresh_token”这类字眼基本可以判断是另一个系统的登录问题别再往天地图的方向排查了。5.3 配额不足与用量监控Token拿到了用得也正常但如果在某个时间点突然大量报错优先去控制台的“用量统计”或“配额管理”页面看一眼。天地图的每个Token通常在单位时间内有请求量上限超过后会出现暂时性的服务拒绝。要避免这个问题可以从几个方向入手在前端代码里尽量做好瓦片缓存避免每次打开页面都重新请求全部瓦片。后端批量调用时加上节流控制每秒请求数不要用for循环无脑猛刷。生产环境尽量通过自己的服务端做数据缓存把天地图的请求量降下来例如把常用区域的POI数据定期拉取到本地数据库。如果项目确实需要大规模高频访问可以在控制台查看是否有更高额度的商务合作或企业版申请通道。5.4 排查Token问题的标准顺序遇到Token相关故障我建议按这个顺序排查效率最高先确认Token本身是否正确在页面或请求里复制出来的Key有没有被截断。再确认参数名是否写对天地图瓦片请求的参数名是tk不是token也不是key。接着确认Key类型浏览器请求用浏览器端Key服务端请求用服务端Key。然后检查白名单浏览器端Key看域名白名单服务端Key看IP白名单。最后看配额登录控制台确认当天请求量是否已超限。大部分问题走到第三步就能定位。如果前三步都没问题再往白名单和配额方向查。不要一上来就怀疑是Token过期天地图Token不同于JWT没有自动refresh机制不会因为“时间到了”就失效。6. 注册和调用过程中容易被忽略的细节6.1 域名白名单的边界问题域名白名单的匹配规则比很多人想象中严格。假如你在控制台填写的是https://example.com但前端页面实际访问地址是https://map.example.com这通常是不能直接匹配通过的。同样如果页面同时使用http://和https://两种协议访问而你只在白名单里配置了其中一个另一个协议下就会出错。所以配置白名单时最好把生产环境、测试环境、本地开发环境的域名和端口一次性梳理清楚分别配置。宁可多配几个白名单项也不要图省事只写一个根域名否则上线后排查起来更痛苦。6.2 服务地址里的子域名编号天地图的瓦片服务地址中常出现t0.tianditu.gov.cn这样的子域名数字0可以替换为0~7。在实际使用中可以用t0到t7的不同子域名分散请求压力也可以固定用一个子域名做测试。需要补充的是服务端偶发单节点异常时切换子域名通常能快速恢复访问这也是一个很实用的小技巧。6.3 Key的安全管理习惯选择了服务端Key就要把它当数据库密码一样谨慎保管。不要提交到Git仓库不要写进前端打包后的JS文件也不要直接在公众号文章里贴出完整Key。比较稳妥的做法是把Key配置在服务器环境变量里代码中通过环境变量读取。定期在控制台重置Key开发环境Key与生产环境Key分开管理。一旦发现Key可能泄露立即在控制台禁用并重新生成。浏览器端Key因为只能在白名单域下使用泄露风险相对可控但也别因此就不设白名单。先配置白名单再上线是一个很好的开发习惯。6.4 先验证再集成能省下大量排错时间我个人的习惯是拿到Token后绝不先写业务代码而是先做“最小可用验证”。在浏览器里直接打开一条拼接好的瓦片请求URL或者在服务器上跑一个最简单的Python请求脚本确认Token有效、服务地址可用、返回结果正常然后再把Token集成到正式项目里。这样做的好处是一旦后续出现问题你可以快速判断问题是出在业务代码上还是出在Token或服务地址本身。很多朋友一上来就写几百行前端代码结果底图不出来排查了半天最后发现只是Token少了几个字符非常浪费时间。在ArcGIS或QGIS里加载天地图时也建议先用软件自带的“添加WMTS服务”功能做一次连通性测试能正常看到底图后再去配置自己的工程文件避免在复杂工程环境里反复折腾坐标系统和缓存。这些年陆续帮不少人处理过天地图接入的问题最常听到的反馈是“注册流程不复杂但配置起来小坑不断”。确实如此Token本身只是一个字符串真正的难点在于理解浏览端与服务端Key的差异、把白名单配对、把坐标系对齐。只要把这几件事理清楚天地图的接入就顺畅了。希望这篇教程能帮你少走一些弯路顺利跑通第一个天地图应用。