做GIS开发或者经常在Web项目里接在线底图的朋友，应该对“天地图”不陌生。它是国内面向公众提供在线地图服务的平台，提供矢量底图、影像底图、地形晕渲、地理编码、逆地理编码等能力，对国内项目来说，最大的好处是访问稳定、数据覆盖好，能直接作为底图服务使用。真正开始用之前，绕不开的一步就是注册天地图Token。这个Token说白了就是你调用天地图各项服务的身份凭证，没有它，接口请求基本都会被拒之门外。
我最早接触天地图的时候，也以为“注册Token”就是注册个账号拿个Key，结果被应用类型、白名单、服务地址这些名词来回折腾了好几轮。这篇就完整写一遍从注册账号、实名认证、创建应用、拿到Token，再到三种常见调用方式的全过程，顺便把Token失效、请求401、配额不够这些高频问题一起梳理清楚，给准备接入天地图的同学做一份能直接照着操作的参考。
1. 搞懂Token之前：天地图能做什么，为什么必须要Token
1.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的区别
这是新手最常踩坑的地方。天地图同一个应用下，通常会有两类Key：
| Key类型 | 使用场景 | 特点 | 安全要求 |
|---|---|---|---|
| 浏览器端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?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILEMATRIX={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?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILEMATRIX={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, params=params, timeout=10) 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，或者页面直接不加载瓦片。我整理了一个速查表，基本覆盖日常高频问题。
| 现象 | 可能原因 | 排查与解决思路 |
|---|---|---|
| 页面请求瓦片返回401 | Token缺失、Token错误、Key类型用错 | 确认URL参数名是否为tk，Key是否正确复制；确认浏览器端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的差异、把白名单配对、把坐标系对齐。只要把这几件事理清楚，天地图的接入就顺畅了。希望这篇教程能帮你少走一些弯路，顺利跑通第一个天地图应用。
