1. 项目概述为什么Unity开发者需要关注天地图API如果你正在用Unity开发涉及地图、位置服务或数字孪生的应用无论是PC端、WebGL还是移动端接入一个稳定、合规且免费的地图底图服务是绕不开的一环。国内很多开发者第一时间会想到高德、百度地图的SDK但对于一些特定需求——比如需要严格遵守地理信息数据使用规定、项目对坐标系有特殊要求或者单纯想尝试不同的地图源——国家基础地理信息中心提供的“天地图”就成了一个非常值得考虑的选项。天地图作为国家地理信息公共服务平台其数据权威、更新稳定并且提供了丰富的API接口。对于Unity开发者而言其WMTSWeb Map Tile Service服务可以直接作为纹理加载到你的地形系统或UI RawImage上快速构建出具有专业级地图背景的应用场景。无论是做智慧城市可视化、物流轨迹追踪还是游戏中的真实世界地图天地图都能提供一个可靠的基础。然而和所有主流在线地图服务一样使用天地图API的第一步就是申请密钥Key并进行安全配置。这个过程本身不复杂但其中关于“IP白名单”的配置环节往往是新手开发者从开发环境切换到生产环境时最容易踩坑的地方。网上很多教程对此一笔带过导致不少人在部署后才发现地图加载不出来调试起来一头雾水。本文就将以一个Unity老鸟的视角手把手带你走通从零申请到安全配置的全流程并重点拆解IP白名单配置中的那些“门道”让你在5分钟内搞定基础配置同时避开未来可能出现的隐患。2. 天地图API密钥申请全流程拆解申请天地图API密钥本身是一个标准化的在线流程但每一步的选择都关系到后续使用的便利性与安全性。我们从头开始确保你申请的密钥是最适合你项目的那一个。2.1 前期准备与账号注册首先你需要访问天地图官方网站的API控制台。这里有一个关键点请务必使用你所在单位或你个人能长期维护的邮箱进行注册不建议使用临时邮箱。因为后续的密钥管理、额度查看以及重要的服务变更通知都会通过这个邮箱发送。注册过程中需要填写开发者信息。如果你是个人开发者如实填写即可如果是企业项目建议使用企业邮箱和统一社会信用代码等信息进行注册这有助于提升账号的信任度也为将来可能申请更高的服务配额尽管免费版通常够用留有余地。注册成功后系统会要求进行邮箱验证完成验证后即可登录控制台。登录后控制台界面可能包含多个服务入口我们直接找到“我的密钥”或“应用管理”相关区域。在创建新密钥之前我们需要先明确一个概念天地图的密钥通常是和应用Application绑定的。一个应用对应一个密钥这样便于你管理不同项目例如一个Unity编辑器工具和一个正式发布的游戏的调用量和权限。2.2 创建应用与获取密钥点击“创建新应用”按钮你会看到需要填写以下几项关键信息应用名称建议填写一个清晰的项目名例如“XX智慧园区Unity客户端”。这纯粹是为了你自己管理方便。应用类型这是第一个关键选择点。对于绝大多数Unity项目尤其是需要加载地图瓦片Tile的场景你应该选择“浏览器端”。因为Unity在运行时无论是编辑器内还是WebGL、PC端打包后调用天地图API获取瓦片其网络请求的源头都被视为“浏览器端”或“客户端”。即使你的Unity应用打包成了Windows的.exe文件它发出的HTTP请求在天地图服务器看来依然是一个客户端请求。除非你是在自己的服务器后端代理转发地图请求这种架构较少见且复杂否则不要选择“服务端”。服务平台这里通常可以勾选“Web端JS API”或保持默认。对于Unity通过HTTP直接请求瓦片URL的方式这个选项影响不大但勾选上更稳妥。绑定域名这是第二个关键点也是最容易与后续IP白名单混淆的地方。这个字段是可选的而且它主要针对的是纯Web前端如JavaScript API的域名校验。对于Unity应用尤其是打包后本地运行或作为桌面端应用没有固定域名这里可以直接留空不填。很多教程强调这里必须填反而误导了Unity开发者。填写完毕后提交系统会立即生成一个唯一的API密钥一串由字母和数字组成的字符串。请立即妥善保存这个密钥控制台虽然可以查看但不会明文再次显示忘记的话只能重新生成。2.3 密钥的安全等级与基础调用拿到密钥后你就可以立即进行简单的测试了。天地图瓦片服务的基础URL模板通常如下https://t{0-7}.tianditu.gov.cn/vec_w/wmts?tk你的密钥这里的t0到t7是负载均衡的子域名vec_w代表矢量地图道路、文字注记cva_w代表矢量注记img_w代表影像地图cia_w代表影像注记。你可以将上述URL中的你的密钥替换直接在浏览器地址栏粘贴访问。如果返回的是XML格式的Capabilities文档描述服务信息的文件而不是错误JSON说明你的密钥在基础层面已经生效了。注意此时你的密钥处于“无限制”状态意味着从任何能访问公网的IP地址发起的请求只要携带了这个密钥都能调用服务。这在开发阶段很方便但也带来了安全风险。如果密钥泄露他人可能会盗用你的配额甚至导致你的服务被停用。因此开发测试完成后配置访问限制是必须的。3. IP白名单配置的核心逻辑与常见误区IP白名单是保护你API密钥不被滥用的核心安全机制。其原理很简单只有在白名单中的IP地址或IP段发出的请求天地图服务器才会受理并返回地图数据不在白名单内的请求即使密钥正确也会被拒绝。3.1 为什么Unity项目必须配置IP白名单对于纯前端网页应用使用“绑定域名”是更常见的限制方式。但Unity应用打包后其运行环境是用户的本地计算机或手机没有固定域名。此时唯一能标识请求来源的就是设备的公网IP地址对于服务器部署的应用则是服务器的公网IP。因此IP白名单就成了Unity这类客户端应用接入天地图服务的标配安全方案。3.2 配置入口与操作步骤在天地图控制台的“我的应用”或“密钥管理”页面找到你刚才创建的应用应该会有“设置”或“安全设置”选项点击进入IP白名单配置界面。配置界面通常是一个文本框允许你以回车分隔的方式输入多个IP地址或CIDR格式的IP段例如192.168.1.0/24。你需要添加哪些IP开发机IP你个人电脑在开发时使用的公网IP。你可以在百度搜索“IP”来快速获取当前公网IP地址。注意家庭宽带或公司网络的公网IP可能是动态的隔一段时间会变化。变化后你需要更新白名单。构建服务器IP如果你有独立的CI/CD服务器如Jenkins来自动打包Unity应用这台服务器的公网IP也需要加入。生产环境服务器IP如果适用如果你的Unity应用是WebGL格式并部署在某个云服务器上那么该云服务器的公网IP必须加入。测试团队IP如果有多人在不同网络环境下测试需要将他们各自网络的公网IP都加入。这在实际项目中可能变得繁琐此时可以考虑使用IP段来简化管理。3.3 关键技巧与避坑指南这里就是经验之谈的重灾区了很多问题都出在这里。技巧一正确处理动态公网IP问题大多数个人开发者使用的是家庭宽带其公网IP是动态分配的可能24小时或重启光猫后就会变化。有几种应对策略策略A临时开发每次IP变化后手动登录控制台更新白名单。适合轻度开发。策略B使用DDNS为你的动态IP配置一个动态域名解析服务但天地图白名单通常只认IP不认域名所以此路不通。策略C最佳实践向你的网络运营商如电信、联通申请办理“公网静态IP”业务。这通常需要是企业宽带或支付额外费用但一劳永逸是小型工作室的推荐选择。策略D使用固定IP的跳板在具有固定公网IP的云服务器上搭建一个简单的反向代理让你的开发机通过这台服务器代理访问天地图服务。这样白名单里只需要配置云服务器的IP。但这种方法增加了架构复杂度和网络延迟。技巧二理解并配置CIDR格式的IP段如果你的公司办公室有一个固定的公网IP段比如123.123.123.0/24那么你可以直接将这个段加入白名单整个办公室的所有电脑就都可以使用了。在配置时务必确认你获取的是公网IP段而不是内网IP段如192.168.x.x或10.x.x.x。你可以联系公司的网络管理员获取此信息。技巧三区分“绑定域名”与“IP白名单”再次强调控制台里可能还有一个“绑定域名”的选项。对于Unity项目除非你的最终发布形式是WebGL并且部署在某个特定域名下否则这个选项与你无关。你的主要精力应该放在IP白名单上。两者是独立的限制条件可以同时生效配置时不要混淆。技巧四白名单生效不是即时的添加或修改IP白名单后通常需要5到15分钟才能在全球服务节点生效。在这期间你可能会遇到间歇性的服务不可用。修改后请耐心等待不要立即断定是配置错误。4. 在Unity中集成与测试天地图服务拿到密钥并配置好IP白名单后就可以在Unity项目中动手集成了。天地图不提供官方的Unity SDK但这反而给了我们最大的灵活性。核心原理就是通过Unity的UnityWebRequest或WWW旧版本类去请求构造好的天地图瓦片URL然后将获取的图片数据应用到材质或UI上。4.1 构建瓦片请求URL首先我们需要根据地图的缩放级别zoom level、瓦片坐标tileX, tileY来动态构建请求URL。以下是一个C#脚本的示例函数public string BuildTianDiTuTileUrl(int zoom, int tileX, int tileY, string layerType vec, string apiKey YOUR_API_KEY_HERE) { // 图层类型映射vec-矢量cva-矢量注记img-影像cia-影像注记 string layer ; switch (layerType) { case vec: layer vec_w; break; case cva: layer cva_w; break; case img: layer img_w; break; case cia: layer cia_w; break; default: layer vec_w; break; } // 使用负载均衡子域名 t0-t7这里简单取模实现随机 string subDomain $t{(tileX tileY) % 8}; // 构建WMTS请求URLKVP方式 string url string.Format(https://{0}.tianditu.gov.cn/{1}/wmts? SERVICEWMTSREQUESTGetTileVERSION1.0.0 LAYER{1}STYLEdefaultTILEMATRIXSETw FORMATtilesTILEMATRIX{2}TILEROW{3}TILECOL{4} tk{5}, subDomain, layer, zoom, tileY, tileX, apiKey); return url; }这个函数构建了一个符合WMTS标准的KVPKey-Value Pair请求URL。关键参数解释TILEMATRIX对应缩放级别zoom。TILEROW和TILECOL对应瓦片的Y和X坐标。注意天地图采用的坐标系原点在左上角Y轴向下这与某些地图标准如TMS不同但上述URL格式是天地图WMTS服务直接接受的无需额外转换。4.2 在Unity中异步加载并显示瓦片接下来我们写一个协程来异步加载瓦片并将其赋给一个Quad或Plane的材质或者一个UI RawImage。using UnityEngine; using UnityEngine.Networking; using System.Collections; public class TileLoader : MonoBehaviour { public string apiKey 你的密钥; public int initialZoom 10; public int tileX 100; public int tileY 50; public Renderer targetRenderer; // 用于3D物体 // public RawImage targetRawImage; // 用于UI IEnumerator Start() { string url BuildTianDiTuTileUrl(initialZoom, tileX, tileY, vec, apiKey); using (UnityWebRequest request UnityWebRequestTexture.GetTexture(url)) { yield return request.SendWebRequest(); if (request.result UnityWebRequest.Result.Success) { Texture2D tileTexture DownloadHandlerTexture.GetContent(request); // 应用到3D物体 if (targetRenderer ! null) { Material mat new Material(Shader.Find(Standard)); mat.mainTexture tileTexture; targetRenderer.material mat; } // 应用到UI // if (targetRawImage ! null) // { // targetRawImage.texture tileTexture; // } Debug.Log(Tile loaded successfully.); } else { Debug.LogError($Failed to load tile: {request.error}); Debug.LogError($Response Code: {request.responseCode}); // 如果返回403错误强烈提示检查IP白名单 if (request.responseCode 403) { Debug.LogError(HTTP 403 Forbidden. This is VERY LIKELY an IP whitelist issue. Please verify your public IP is correctly added to the whitelist in Tianditu console.); } } } } }4.3 实现一个简单的地图查看器单张瓦片意义不大我们需要一个能根据视野动态加载瓦片的地图管理器。这涉及到墨卡托投影坐标与瓦片坐标的转换、视野内瓦片索引的计算、瓦片对象的缓存与回收等。这里给出一个高度简化的核心思路框架坐标转换将Unity世界坐标或经纬度转换为网络墨卡托坐标Web MercatorEPSG:3857再根据当前缩放级别计算出对应的瓦片坐标tileX, tileY。视野计算根据主摄像机的位置和视锥体计算出当前视野范围所覆盖的瓦片行列号范围。异步加载队列为视野内的每一块瓦片创建一个加载任务使用上述协程并管理一个加载队列避免同一帧发起过多网络请求。缓存与复用将加载好的瓦片Texture缓存起来当视野移动时复用在缓存中的瓦片只加载新进入视野的瓦片并销毁移出视野的瓦片对象以节省内存和性能。瓦片布局将加载好的瓦片纹理按照其瓦片坐标精准地摆放在Unity世界中的对应位置拼接成完整的地图。这部分代码量较大但网上有成熟的开源Unity地图插件如Mapbox SDK for Unity的架构思路可供参考你可以基于其架构将数据源替换为天地图的URL。核心就是做好异步加载管理和坐标转换。5. 从开发到生产环境切换与问题排查实录当你顺利在编辑器中看到地图后真正的挑战可能才刚刚开始打包发布到不同平台和环境时遇到的各种问题。5.1 开发、测试与生产环境的白名单管理这是一个典型的DevOps场景开发环境添加你个人电脑和同事电脑的动态/静态公网IP。测试环境如果有一个独立的测试服务器添加该服务器IP。如果是让测试人员在各处测试可以考虑在测试阶段暂时放宽限制有风险或收集所有测试点的IP较繁琐。生产环境这是最重要的。客户端应用PC、移动端这几乎无法为每个用户配置IP白名单。对于此类项目天地图API可能不是最合适的选择因为每个终端用户的IP都不同且不可控。你需要考虑使用服务端代理方案你的服务器固定IP去请求天地图然后转发给客户端或者换用支持“浏览器端密钥Referer校验”的其他服务但天地图对此支持不明确。这是技术选型初期就必须评估的关键点WebGL应用如果你的Unity项目打包成WebGL并部署在云服务器如阿里云ECS上那么用户是通过浏览器访问你的服务器IP或域名来加载页面的。此时地图请求是从用户的浏览器直接发往天地图服务器的。因此你需要添加的是你的WebGL应用所部署的那台云服务器的公网IP而不是用户的IP。所有用户共享这个出口IP。服务器端应用如果你的Unity应用作为后端服务运行在服务器上那么只添加服务器IP即可。最佳实践建议在天地图控制台为开发、测试、生产分别创建不同的应用和密钥。这样每个环境有独立的密钥和IP白名单互不干扰也便于监控各环境的使用量一旦某个环境的密钥泄露可以单独重置不影响其他环境。5.2 高频问题排查清单当你发现地图加载失败时可以按照以下清单逐项排查问题现象可能原因排查步骤与解决方案编辑器内可加载打包后无法加载1. 打包后运行环境的公网IP不在白名单内。2. WebGL构建的服务器IP未添加。3. 代码中密钥硬编码打包时被混淆或丢失。1. 在打包后的应用中输出或打印其网络请求的完整URL含密钥检查密钥是否正确。注意切勿在公开场合打印带密钥的URL2. 确认打包后运行设备/环境的公网IP并加入白名单。3. 对于WebGL检查部署服务器的公网IP。一直加载失败控制台报403错误IP白名单配置错误或未生效。1. 确认你当前设备的公网IP用浏览器查IP。2. 登录天地图控制台核对白名单中是否有此IP格式是否正确不要有空格用回车分隔。3.等待5-15分钟再试白名单生效有延迟。4. 检查是否配置了“绑定域名”如果配置了且不匹配也会导致403。Unity项目通常不应绑定域名。地图能加载但位置偏移坐标系或瓦片索引计算错误。1. 确保你的坐标转换逻辑正确。Unity世界坐标、经纬度、Web墨卡托坐标、瓦片坐标之间的转换公式要核对。2. 检查瓦片URL中的TILEROW和TILECOL参数计算是否正确。可以手动固定一个已知的zoom/x/y用浏览器测试URL是否能返回正确位置的瓦片图片。加载缓慢或部分瓦片缺失网络问题或天地图服务节点不稳定。1. 天地图的t0-t7是负载均衡节点可以尝试在代码中固定使用其中一个如t0看是否改善。或者实现失败重试并切换节点。2. 检查是否触发了频率限制。免费服务有调用频次限制过于频繁的请求可能导致短暂拦截。实现请求队列和间隔延迟。在移动设备手机上无法加载移动网络IP变化频繁且可能不在白名单内。这是客户端应用的硬伤。除非你能获取到用户IP并动态更新白名单不现实否则此方案不适用于公开发布的移动端App。考虑服务端代理方案或更换地图服务商。5.3 性能优化与进阶技巧纹理压缩与Mipmapping下载的瓦片纹理尺寸通常是256x256或512x512。在导入Unity后可以为其设置合适的压缩格式如ASTC并生成Mipmap这在3D场景中远处观察地图时能提升性能和视觉质量。异步加载与对象池务必使用协程或async/await进行异步加载避免阻塞主线程。对于瓦片GameObject使用对象池进行管理频繁的Instantiate和Destroy会造成GC压力。错误重试与降级网络请求必然可能失败。实现一个简单的重试机制如最多重试3次每次间隔递增。对于始终加载失败的瓦片可以显示一个默认的错误纹理如灰色格子避免地图上出现空洞。配额监控定期登录天地图控制台查看API调用次数和配额使用情况。免费配额对于一般应用足够但高频应用需要留意。最后关于密钥安全再啰嗦一句永远不要将写死的API密钥提交到公开的代码仓库如GitHub。在Unity中可以使用Resources文件夹下的配置文件、或通过环境变量、或在构建时由CI/CD流程注入等方式来管理密钥。对于客户端应用密钥泄露风险始终存在这也是为什么IP白名单和服务端代理方案如此重要的原因。集成第三方服务就像搭积木每一步的扎实程度决定了最终建筑的稳定性。处理好天地图API密钥和IP白名单你的Unity数字地图就拥有了一个可靠的基础。剩下的就是尽情发挥你的创意在那片广阔的数字疆域上构建你的世界了。
Unity集成天地图API：从密钥申请到IP白名单配置全攻略
发布时间：2026/7/11 21:58:44
1. 项目概述为什么Unity开发者需要关注天地图API如果你正在用Unity开发涉及地图、位置服务或数字孪生的应用无论是PC端、WebGL还是移动端接入一个稳定、合规且免费的地图底图服务是绕不开的一环。国内很多开发者第一时间会想到高德、百度地图的SDK但对于一些特定需求——比如需要严格遵守地理信息数据使用规定、项目对坐标系有特殊要求或者单纯想尝试不同的地图源——国家基础地理信息中心提供的“天地图”就成了一个非常值得考虑的选项。天地图作为国家地理信息公共服务平台其数据权威、更新稳定并且提供了丰富的API接口。对于Unity开发者而言其WMTSWeb Map Tile Service服务可以直接作为纹理加载到你的地形系统或UI RawImage上快速构建出具有专业级地图背景的应用场景。无论是做智慧城市可视化、物流轨迹追踪还是游戏中的真实世界地图天地图都能提供一个可靠的基础。然而和所有主流在线地图服务一样使用天地图API的第一步就是申请密钥Key并进行安全配置。这个过程本身不复杂但其中关于“IP白名单”的配置环节往往是新手开发者从开发环境切换到生产环境时最容易踩坑的地方。网上很多教程对此一笔带过导致不少人在部署后才发现地图加载不出来调试起来一头雾水。本文就将以一个Unity老鸟的视角手把手带你走通从零申请到安全配置的全流程并重点拆解IP白名单配置中的那些“门道”让你在5分钟内搞定基础配置同时避开未来可能出现的隐患。2. 天地图API密钥申请全流程拆解申请天地图API密钥本身是一个标准化的在线流程但每一步的选择都关系到后续使用的便利性与安全性。我们从头开始确保你申请的密钥是最适合你项目的那一个。2.1 前期准备与账号注册首先你需要访问天地图官方网站的API控制台。这里有一个关键点请务必使用你所在单位或你个人能长期维护的邮箱进行注册不建议使用临时邮箱。因为后续的密钥管理、额度查看以及重要的服务变更通知都会通过这个邮箱发送。注册过程中需要填写开发者信息。如果你是个人开发者如实填写即可如果是企业项目建议使用企业邮箱和统一社会信用代码等信息进行注册这有助于提升账号的信任度也为将来可能申请更高的服务配额尽管免费版通常够用留有余地。注册成功后系统会要求进行邮箱验证完成验证后即可登录控制台。登录后控制台界面可能包含多个服务入口我们直接找到“我的密钥”或“应用管理”相关区域。在创建新密钥之前我们需要先明确一个概念天地图的密钥通常是和应用Application绑定的。一个应用对应一个密钥这样便于你管理不同项目例如一个Unity编辑器工具和一个正式发布的游戏的调用量和权限。2.2 创建应用与获取密钥点击“创建新应用”按钮你会看到需要填写以下几项关键信息应用名称建议填写一个清晰的项目名例如“XX智慧园区Unity客户端”。这纯粹是为了你自己管理方便。应用类型这是第一个关键选择点。对于绝大多数Unity项目尤其是需要加载地图瓦片Tile的场景你应该选择“浏览器端”。因为Unity在运行时无论是编辑器内还是WebGL、PC端打包后调用天地图API获取瓦片其网络请求的源头都被视为“浏览器端”或“客户端”。即使你的Unity应用打包成了Windows的.exe文件它发出的HTTP请求在天地图服务器看来依然是一个客户端请求。除非你是在自己的服务器后端代理转发地图请求这种架构较少见且复杂否则不要选择“服务端”。服务平台这里通常可以勾选“Web端JS API”或保持默认。对于Unity通过HTTP直接请求瓦片URL的方式这个选项影响不大但勾选上更稳妥。绑定域名这是第二个关键点也是最容易与后续IP白名单混淆的地方。这个字段是可选的而且它主要针对的是纯Web前端如JavaScript API的域名校验。对于Unity应用尤其是打包后本地运行或作为桌面端应用没有固定域名这里可以直接留空不填。很多教程强调这里必须填反而误导了Unity开发者。填写完毕后提交系统会立即生成一个唯一的API密钥一串由字母和数字组成的字符串。请立即妥善保存这个密钥控制台虽然可以查看但不会明文再次显示忘记的话只能重新生成。2.3 密钥的安全等级与基础调用拿到密钥后你就可以立即进行简单的测试了。天地图瓦片服务的基础URL模板通常如下https://t{0-7}.tianditu.gov.cn/vec_w/wmts?tk你的密钥这里的t0到t7是负载均衡的子域名vec_w代表矢量地图道路、文字注记cva_w代表矢量注记img_w代表影像地图cia_w代表影像注记。你可以将上述URL中的你的密钥替换直接在浏览器地址栏粘贴访问。如果返回的是XML格式的Capabilities文档描述服务信息的文件而不是错误JSON说明你的密钥在基础层面已经生效了。注意此时你的密钥处于“无限制”状态意味着从任何能访问公网的IP地址发起的请求只要携带了这个密钥都能调用服务。这在开发阶段很方便但也带来了安全风险。如果密钥泄露他人可能会盗用你的配额甚至导致你的服务被停用。因此开发测试完成后配置访问限制是必须的。3. IP白名单配置的核心逻辑与常见误区IP白名单是保护你API密钥不被滥用的核心安全机制。其原理很简单只有在白名单中的IP地址或IP段发出的请求天地图服务器才会受理并返回地图数据不在白名单内的请求即使密钥正确也会被拒绝。3.1 为什么Unity项目必须配置IP白名单对于纯前端网页应用使用“绑定域名”是更常见的限制方式。但Unity应用打包后其运行环境是用户的本地计算机或手机没有固定域名。此时唯一能标识请求来源的就是设备的公网IP地址对于服务器部署的应用则是服务器的公网IP。因此IP白名单就成了Unity这类客户端应用接入天地图服务的标配安全方案。3.2 配置入口与操作步骤在天地图控制台的“我的应用”或“密钥管理”页面找到你刚才创建的应用应该会有“设置”或“安全设置”选项点击进入IP白名单配置界面。配置界面通常是一个文本框允许你以回车分隔的方式输入多个IP地址或CIDR格式的IP段例如192.168.1.0/24。你需要添加哪些IP开发机IP你个人电脑在开发时使用的公网IP。你可以在百度搜索“IP”来快速获取当前公网IP地址。注意家庭宽带或公司网络的公网IP可能是动态的隔一段时间会变化。变化后你需要更新白名单。构建服务器IP如果你有独立的CI/CD服务器如Jenkins来自动打包Unity应用这台服务器的公网IP也需要加入。生产环境服务器IP如果适用如果你的Unity应用是WebGL格式并部署在某个云服务器上那么该云服务器的公网IP必须加入。测试团队IP如果有多人在不同网络环境下测试需要将他们各自网络的公网IP都加入。这在实际项目中可能变得繁琐此时可以考虑使用IP段来简化管理。3.3 关键技巧与避坑指南这里就是经验之谈的重灾区了很多问题都出在这里。技巧一正确处理动态公网IP问题大多数个人开发者使用的是家庭宽带其公网IP是动态分配的可能24小时或重启光猫后就会变化。有几种应对策略策略A临时开发每次IP变化后手动登录控制台更新白名单。适合轻度开发。策略B使用DDNS为你的动态IP配置一个动态域名解析服务但天地图白名单通常只认IP不认域名所以此路不通。策略C最佳实践向你的网络运营商如电信、联通申请办理“公网静态IP”业务。这通常需要是企业宽带或支付额外费用但一劳永逸是小型工作室的推荐选择。策略D使用固定IP的跳板在具有固定公网IP的云服务器上搭建一个简单的反向代理让你的开发机通过这台服务器代理访问天地图服务。这样白名单里只需要配置云服务器的IP。但这种方法增加了架构复杂度和网络延迟。技巧二理解并配置CIDR格式的IP段如果你的公司办公室有一个固定的公网IP段比如123.123.123.0/24那么你可以直接将这个段加入白名单整个办公室的所有电脑就都可以使用了。在配置时务必确认你获取的是公网IP段而不是内网IP段如192.168.x.x或10.x.x.x。你可以联系公司的网络管理员获取此信息。技巧三区分“绑定域名”与“IP白名单”再次强调控制台里可能还有一个“绑定域名”的选项。对于Unity项目除非你的最终发布形式是WebGL并且部署在某个特定域名下否则这个选项与你无关。你的主要精力应该放在IP白名单上。两者是独立的限制条件可以同时生效配置时不要混淆。技巧四白名单生效不是即时的添加或修改IP白名单后通常需要5到15分钟才能在全球服务节点生效。在这期间你可能会遇到间歇性的服务不可用。修改后请耐心等待不要立即断定是配置错误。4. 在Unity中集成与测试天地图服务拿到密钥并配置好IP白名单后就可以在Unity项目中动手集成了。天地图不提供官方的Unity SDK但这反而给了我们最大的灵活性。核心原理就是通过Unity的UnityWebRequest或WWW旧版本类去请求构造好的天地图瓦片URL然后将获取的图片数据应用到材质或UI上。4.1 构建瓦片请求URL首先我们需要根据地图的缩放级别zoom level、瓦片坐标tileX, tileY来动态构建请求URL。以下是一个C#脚本的示例函数public string BuildTianDiTuTileUrl(int zoom, int tileX, int tileY, string layerType vec, string apiKey YOUR_API_KEY_HERE) { // 图层类型映射vec-矢量cva-矢量注记img-影像cia-影像注记 string layer ; switch (layerType) { case vec: layer vec_w; break; case cva: layer cva_w; break; case img: layer img_w; break; case cia: layer cia_w; break; default: layer vec_w; break; } // 使用负载均衡子域名 t0-t7这里简单取模实现随机 string subDomain $t{(tileX tileY) % 8}; // 构建WMTS请求URLKVP方式 string url string.Format(https://{0}.tianditu.gov.cn/{1}/wmts? SERVICEWMTSREQUESTGetTileVERSION1.0.0 LAYER{1}STYLEdefaultTILEMATRIXSETw FORMATtilesTILEMATRIX{2}TILEROW{3}TILECOL{4} tk{5}, subDomain, layer, zoom, tileY, tileX, apiKey); return url; }这个函数构建了一个符合WMTS标准的KVPKey-Value Pair请求URL。关键参数解释TILEMATRIX对应缩放级别zoom。TILEROW和TILECOL对应瓦片的Y和X坐标。注意天地图采用的坐标系原点在左上角Y轴向下这与某些地图标准如TMS不同但上述URL格式是天地图WMTS服务直接接受的无需额外转换。4.2 在Unity中异步加载并显示瓦片接下来我们写一个协程来异步加载瓦片并将其赋给一个Quad或Plane的材质或者一个UI RawImage。using UnityEngine; using UnityEngine.Networking; using System.Collections; public class TileLoader : MonoBehaviour { public string apiKey 你的密钥; public int initialZoom 10; public int tileX 100; public int tileY 50; public Renderer targetRenderer; // 用于3D物体 // public RawImage targetRawImage; // 用于UI IEnumerator Start() { string url BuildTianDiTuTileUrl(initialZoom, tileX, tileY, vec, apiKey); using (UnityWebRequest request UnityWebRequestTexture.GetTexture(url)) { yield return request.SendWebRequest(); if (request.result UnityWebRequest.Result.Success) { Texture2D tileTexture DownloadHandlerTexture.GetContent(request); // 应用到3D物体 if (targetRenderer ! null) { Material mat new Material(Shader.Find(Standard)); mat.mainTexture tileTexture; targetRenderer.material mat; } // 应用到UI // if (targetRawImage ! null) // { // targetRawImage.texture tileTexture; // } Debug.Log(Tile loaded successfully.); } else { Debug.LogError($Failed to load tile: {request.error}); Debug.LogError($Response Code: {request.responseCode}); // 如果返回403错误强烈提示检查IP白名单 if (request.responseCode 403) { Debug.LogError(HTTP 403 Forbidden. This is VERY LIKELY an IP whitelist issue. Please verify your public IP is correctly added to the whitelist in Tianditu console.); } } } } }4.3 实现一个简单的地图查看器单张瓦片意义不大我们需要一个能根据视野动态加载瓦片的地图管理器。这涉及到墨卡托投影坐标与瓦片坐标的转换、视野内瓦片索引的计算、瓦片对象的缓存与回收等。这里给出一个高度简化的核心思路框架坐标转换将Unity世界坐标或经纬度转换为网络墨卡托坐标Web MercatorEPSG:3857再根据当前缩放级别计算出对应的瓦片坐标tileX, tileY。视野计算根据主摄像机的位置和视锥体计算出当前视野范围所覆盖的瓦片行列号范围。异步加载队列为视野内的每一块瓦片创建一个加载任务使用上述协程并管理一个加载队列避免同一帧发起过多网络请求。缓存与复用将加载好的瓦片Texture缓存起来当视野移动时复用在缓存中的瓦片只加载新进入视野的瓦片并销毁移出视野的瓦片对象以节省内存和性能。瓦片布局将加载好的瓦片纹理按照其瓦片坐标精准地摆放在Unity世界中的对应位置拼接成完整的地图。这部分代码量较大但网上有成熟的开源Unity地图插件如Mapbox SDK for Unity的架构思路可供参考你可以基于其架构将数据源替换为天地图的URL。核心就是做好异步加载管理和坐标转换。5. 从开发到生产环境切换与问题排查实录当你顺利在编辑器中看到地图后真正的挑战可能才刚刚开始打包发布到不同平台和环境时遇到的各种问题。5.1 开发、测试与生产环境的白名单管理这是一个典型的DevOps场景开发环境添加你个人电脑和同事电脑的动态/静态公网IP。测试环境如果有一个独立的测试服务器添加该服务器IP。如果是让测试人员在各处测试可以考虑在测试阶段暂时放宽限制有风险或收集所有测试点的IP较繁琐。生产环境这是最重要的。客户端应用PC、移动端这几乎无法为每个用户配置IP白名单。对于此类项目天地图API可能不是最合适的选择因为每个终端用户的IP都不同且不可控。你需要考虑使用服务端代理方案你的服务器固定IP去请求天地图然后转发给客户端或者换用支持“浏览器端密钥Referer校验”的其他服务但天地图对此支持不明确。这是技术选型初期就必须评估的关键点WebGL应用如果你的Unity项目打包成WebGL并部署在云服务器如阿里云ECS上那么用户是通过浏览器访问你的服务器IP或域名来加载页面的。此时地图请求是从用户的浏览器直接发往天地图服务器的。因此你需要添加的是你的WebGL应用所部署的那台云服务器的公网IP而不是用户的IP。所有用户共享这个出口IP。服务器端应用如果你的Unity应用作为后端服务运行在服务器上那么只添加服务器IP即可。最佳实践建议在天地图控制台为开发、测试、生产分别创建不同的应用和密钥。这样每个环境有独立的密钥和IP白名单互不干扰也便于监控各环境的使用量一旦某个环境的密钥泄露可以单独重置不影响其他环境。5.2 高频问题排查清单当你发现地图加载失败时可以按照以下清单逐项排查问题现象可能原因排查步骤与解决方案编辑器内可加载打包后无法加载1. 打包后运行环境的公网IP不在白名单内。2. WebGL构建的服务器IP未添加。3. 代码中密钥硬编码打包时被混淆或丢失。1. 在打包后的应用中输出或打印其网络请求的完整URL含密钥检查密钥是否正确。注意切勿在公开场合打印带密钥的URL2. 确认打包后运行设备/环境的公网IP并加入白名单。3. 对于WebGL检查部署服务器的公网IP。一直加载失败控制台报403错误IP白名单配置错误或未生效。1. 确认你当前设备的公网IP用浏览器查IP。2. 登录天地图控制台核对白名单中是否有此IP格式是否正确不要有空格用回车分隔。3.等待5-15分钟再试白名单生效有延迟。4. 检查是否配置了“绑定域名”如果配置了且不匹配也会导致403。Unity项目通常不应绑定域名。地图能加载但位置偏移坐标系或瓦片索引计算错误。1. 确保你的坐标转换逻辑正确。Unity世界坐标、经纬度、Web墨卡托坐标、瓦片坐标之间的转换公式要核对。2. 检查瓦片URL中的TILEROW和TILECOL参数计算是否正确。可以手动固定一个已知的zoom/x/y用浏览器测试URL是否能返回正确位置的瓦片图片。加载缓慢或部分瓦片缺失网络问题或天地图服务节点不稳定。1. 天地图的t0-t7是负载均衡节点可以尝试在代码中固定使用其中一个如t0看是否改善。或者实现失败重试并切换节点。2. 检查是否触发了频率限制。免费服务有调用频次限制过于频繁的请求可能导致短暂拦截。实现请求队列和间隔延迟。在移动设备手机上无法加载移动网络IP变化频繁且可能不在白名单内。这是客户端应用的硬伤。除非你能获取到用户IP并动态更新白名单不现实否则此方案不适用于公开发布的移动端App。考虑服务端代理方案或更换地图服务商。5.3 性能优化与进阶技巧纹理压缩与Mipmapping下载的瓦片纹理尺寸通常是256x256或512x512。在导入Unity后可以为其设置合适的压缩格式如ASTC并生成Mipmap这在3D场景中远处观察地图时能提升性能和视觉质量。异步加载与对象池务必使用协程或async/await进行异步加载避免阻塞主线程。对于瓦片GameObject使用对象池进行管理频繁的Instantiate和Destroy会造成GC压力。错误重试与降级网络请求必然可能失败。实现一个简单的重试机制如最多重试3次每次间隔递增。对于始终加载失败的瓦片可以显示一个默认的错误纹理如灰色格子避免地图上出现空洞。配额监控定期登录天地图控制台查看API调用次数和配额使用情况。免费配额对于一般应用足够但高频应用需要留意。最后关于密钥安全再啰嗦一句永远不要将写死的API密钥提交到公开的代码仓库如GitHub。在Unity中可以使用Resources文件夹下的配置文件、或通过环境变量、或在构建时由CI/CD流程注入等方式来管理密钥。对于客户端应用密钥泄露风险始终存在这也是为什么IP白名单和服务端代理方案如此重要的原因。集成第三方服务就像搭积木每一步的扎实程度决定了最终建筑的稳定性。处理好天地图API密钥和IP白名单你的Unity数字地图就拥有了一个可靠的基础。剩下的就是尽情发挥你的创意在那片广阔的数字疆域上构建你的世界了。
