1. 项目概述为什么Unity开发者需要关注天地图API如果你正在用Unity开发涉及地图、位置服务或地理信息可视化的项目无论是智慧城市、物流仿真、文旅导览还是游戏中的真实世界场景那么“天地图”这个名字你一定不陌生。作为国内权威的地理信息服务它提供了包括矢量、影像、地形在内的多种底图服务数据权威、更新及时且对开发者相对友好。但很多Unity开发者在接入时第一步——申请API密钥和配置IP白名单——就卡住了要么是流程不熟要么是配置后服务依然无法调用尤其是在WebGL平台或服务器部署时问题频发。我自己在多个商业项目中集成过天地图从PC端应用到移动端App再到WebGL的网页应用几乎把所有能踩的坑都踩了一遍。我发现网上很多教程只讲了“点击这里、填写那里”的步骤却没说清楚背后的逻辑比如“应用类型”到底怎么选、“安全设置”里的IP白名单有什么门道、为什么在Unity编辑器里测试正常一打包发布就报“您的密钥无效”。这导致开发者照着做也未必能成功反复折腾浪费大量时间。这篇文章我就以一个Unity老鸟的身份带你彻底搞懂天地图API密钥从申请到安全配置的全过程。目标很明确5分钟完成申请是基础更重要的是让你理解每一个配置项的意义掌握IP白名单设置的核心理念和技巧确保你的密钥在开发、测试、生产全生命周期中都安全、稳定、可用。我们会结合Unity开发中常见的场景特别是WebGL这个“老大难”平台把那些官方文档里没写、但实践中至关重要的细节掰开揉碎讲清楚。2. 天地图API密钥申请全流程拆解与避坑指南申请一个天地图API密钥表面上看就是在官网上填个表单但里面的每一个选项都直接关系到你后续开发的顺畅程度。很多人申请时随便一填到了用的时候才发现各种限制回头重新申请反而更麻烦。2.1 前期准备与平台选择首先访问“国家地理信息公共服务平台”俗称天地图官网。你需要注册一个个人或企业账号。这里有个小建议如果是商业项目强烈建议使用企业身份注册和申请。个人账号虽然快捷但在调用量配额、服务稳定性支持以及未来可能涉及的法律合规性上企业账号更有保障。注册过程按部就班即可需要手机号和邮箱验证。登录后进入“控制台”或“我的密钥”页面开始创建应用。第一个关键选择来了“应用类型”。这里通常有“浏览器端”、“服务器端”、“移动端”等选项。Unity编辑器内测试与PC/Mac独立平台这属于浏览器端吗严格来说Unity编辑器本身和打包后的桌面应用.exe, .app并非通过浏览器运行。但是天地图的“浏览器端”密钥校验机制通常是基于HTTP Referer请求来源或IP。在本地运行时这些信息可能为空或不固定。经过实测对于在本地localhost环境或本地文件系统file://中测试的Unity项目包括编辑器Play模式选择“浏览器端”并做特殊配置后面IP白名单会讲通常是可行的。但更稳妥的做法是如果应用最终是桌面端且不需要从公网访问天地图服务可以优先考虑是否需要API密钥某些本地化部署方案可能通过其他方式解决。Unity WebGL平台这是绝对的重灾区必须选择“浏览器端”。因为WebGL应用最终是运行在用户的浏览器中的所有对天地图服务的请求都是从最终用户的IP发出的。这是理解后续所有配置的基石。移动端iOS/Android如果您的Unity应用打包成手机App情况类似WebGL。虽然它是一个原生应用但其中用于显示地图的WebView或网络请求源头是用户设备的IP。因此通常也建议选择“浏览器端”并配合动态IP策略即不设IP白名单但启用其他安全措施。少数需要服务器中转地图瓦片的情况除外。服务端调用如果你的Unity项目有一个后端服务器需要服务器去请求天地图的数据然后处理后再发给客户端那么你必须额外申请一个“服务器端”密钥。这个密钥的校验是基于服务器公网IP的。避坑心得1我的建议是为不同的运行环境创建不同的密钥。例如单独为“WebGL测试环境”创建一个浏览器端密钥为“生产环境服务器”创建一个服务器端密钥。这样做的好处是权限隔离即使测试密钥泄露也不会影响线上服务同时也方便对不同密钥的调用量进行独立监控和管理。2.2 关键信息填写与“安全设置”深度解析创建应用时你需要填写应用名称、描述等信息这些按实填写即可。核心在于“安全设置”部分这里直接决定了你的密钥能否被成功调用。安全设置主要包含两大块Referer白名单和IP白名单。对于Unity开发者而言IP白名单是重中之重也是困惑最多的地方。Referer请求来源白名单是什么HTTP请求头中的一个字段用来告诉服务器这个请求是从哪个页面链接过来的。主要用于保护网页应用。Unity相关场景对于WebGL应用如果你的游戏页面部署在https://yourgame.com那么你可以将https://yourgame.com/*加入Referer白名单。这样只有从这个域名下发出的请求才会被天地图服务器认可。怎么填支持通配符*。例如https://localhost:*表示允许所有本地localhost端口用于开发测试。https://*.yourcompany.com/*表示允许公司所有子域名。重要限制很多开发者不知道Referer校验在本地文件file://协议和某些严格的安全环境下可能为空或被浏览器禁止发送。这意味着如果你直接用浏览器打开本地的WebGL构建的HTML文件Referer是空的会导致校验失败。这是本地测试常见的一个坑。IP白名单是什么允许访问天地图服务的服务器或客户端的公网IP地址列表。这是比Referer更常用、也更关键的防护手段。Unity核心难题Unity应用运行环境的IP是不确定的。编辑器/PC端开发者的机器IP可能是家庭或公司的动态IP。WebGL用户遍布全球IP千变万化。移动端用户使用4G/5G或不同Wi-FiIP随时在变。策略选择情况A需要固定服务器IP中转。这是最推荐给WebGL和移动端的生产环境方案。你不直接让客户端请求天地图而是在你的服务器上写一个代理接口。客户端请求你的服务器你的服务器使用服务器端密钥再去请求天地图然后将数据返回给客户端。此时你只需要在服务器端密钥的IP白名单中填入你服务器的公网IP即可。客户端密钥浏览器端的IP白名单可以留空或填写0.0.0.0/0允许所有IP但需配合Referer等其他限制。情况B客户端直连且用户IP不确定。对于测试、演示或用户量可控的内部项目你可能不得不让客户端直连。这时IP白名单必须留空。留空意味着“不启用IP白名单校验”天地图仅通过密钥本身来验证。这是一个极其重要的技巧很多开发者误以为必须填个IP结果填了自家IP导致其他用户无法使用。情况C开发测试环境。如果你希望在办公室或家里固定IP的环境下测试客户端直连可以将你的当前公网IP填入。但注意家庭宽带IP可能会重启变化公司网络可能出口IP不止一个。避坑心得2在控制台填写IP白名单时天地图支持两种格式单个IP如123.123.123.123和CIDR格式网段如123.123.123.0/24。如果你使用云服务器务必在服务器控制台查看其公网IP而不是内网IP。一个快速获取本机公网IP的方法是打开浏览器搜索“我的IP”。2.3 申请完成后的关键动作提交申请后通常很快就能获得一串密钥一串字符串。拿到密钥后不要急着把它硬编码到你的Unity脚本里。你应该立刻做以下几件事环境变量管理将密钥存储在Unity的PlayerSettings中作为一个自定义脚本定义符号或者使用一个不提交到版本库的配置文件如Resources目录下的一个加密文本或通过Unity的Cloud Config。绝对不要将密钥明文上传到Git等公共仓库。立即进行最小化测试写一个最简单的脚本在Start函数里用UnityWebRequest去请求一个天地图最简单的瓦片URL并把你的密钥作为参数拼接上去。在编辑器里运行查看控制台日志。如果返回错误信息可以根据错误码如1001代表密钥错误1002代表IP或Referer不允许快速定位是密钥问题还是安全设置问题。记录密钥与应用的对应关系在项目文档或密码管理工具中清晰记录这个密钥对应的应用名称、平台WebGL/移动端、安全设置IP白名单规则方便日后维护和轮换。3. IP白名单设置的核心技巧与多场景实战理解了IP白名单的原理后我们来针对Unity开发中最典型的几个场景给出具体的配置方案和技巧。3.1 场景一Unity编辑器与PC独立平台开发测试目标在Unity编辑器的Play模式以及打包出的PC/Mac独立应用中能正常加载天地图。挑战应用运行在本机其网络请求出口IP是你机器的公网IP。家庭宽带IP常变公司网络可能有统一出口代理IP相对固定但可能多个。配置方案为这个测试环境单独申请一个“浏览器端”密钥。IP白名单填入你当前开发机的公网IP。如果你在公司需要询问运维人员公司的外网出口IP段并可能需要用CIDR格式如202.120.10.0/24来覆盖整个办公网段。Referer白名单留空或填写http://localhost:*和file://*如果支持。注意并非所有地图API SDK都支持file://协议。实操技巧写一个小的编辑器工具脚本定期比如每天启动Unity时调用一个IP查询接口获取本机公网IP并提示开发者是否需要更新控制台的白名单。这能应对家庭IP变化的问题。如果公司网络复杂可以尝试在测试阶段暂时清空IP白名单完成基本功能测试。但上线前必须确定最终的网络架构。3.2 场景二Unity WebGL平台最复杂场景目标将Unity项目构建为WebGL并部署到服务器后用户通过浏览器能正常看到天地图。挑战用户IP未知且动态浏览器安全策略CORS限制本地file://协议测试困难。推荐配置方案生产环境最佳实践架构采用“客户端 - 你的服务器 - 天地图”的代理模式。密钥配置客户端浏览器端密钥申请一个其IP白名单留空。Referer白名单填写你的网站域名例如https://game.yourdomain.com/*。这个密钥实际上可能只用于一些不需要IP校验的轻量级服务或者干脆不用。核心的地图瓦片请求不走这个密钥。服务器端服务器端密钥申请一个其IP白名单严格填写你的应用服务器公网IP。这个密钥用于你的服务器代理程序去合法地获取天地图数据。Unity中的实现你不能直接使用天地图的瓦片URL模板。你需要编写一个简单的后端服务可以用Node.js、Python Flask、C# ASP.NET Core等接收客户端传来的地图瓦片坐标z, x, y或范围参数然后用服务器端密钥向天地图发起请求获取到图片数据后再返回给客户端的Unity WebGL应用。优势安全你的服务器端密钥IP固定非常安全。客户端密钥即使暴露攻击者也无法直接高频率调用天地图受你服务器代理的逻辑控制。可控可以在服务器端加入缓存、限流、日志监控。绕过CORS服务器代理天然解决了浏览器跨域问题。备选方案仅用于演示或低频内部应用如果必须客户端直连则申请一个“浏览器端”密钥。IP白名单留空。Referer白名单必须严格设置为你部署的域名例如https://demo.yourdomain.com/*。这能提供最基本的一层防护。在Unity中使用UnityWebRequest或相关地图插件如Mapbox Unity SDK的适配层发起请求。避坑心得3WebGL本地测试。这是个大坑。如果你用浏览器直接打开本地构建的index.htmlfile://协议由于安全限制UnityWebRequest可能无法正常工作且Referer为空。解决方案有使用一个简单的本地HTTP服务器来托管你的WebGL构建文件。例如在构建目录下运行python -m http.server 8000然后通过http://localhost:8000访问。这样就有了一个合法的本地域名和Referer。在Unity的Player Settings - WebGL - Publishing Settings中可以尝试调整“WebGL模板”或启用“Development Build”来获得更详细的错误信息。3.3 场景三iOS/Android移动端平台目标打包后的移动App能显示天地图。挑战移动网络4G/5G和不同Wi-Fi下的IP动态变化App内WebView或网络请求的标识。配置方案方案A类似WebGL代理推荐为移动App配备一个后端服务器所有地图请求通过你的服务器代理转发。配置同上文WebGL最佳实践。这是最安全、最可控的方式尤其适合需要展示大量地图数据或进行地理计算的商业应用。方案B客户端直连申请“浏览器端”密钥。IP白名单留空。Referer白名单如何处理移动端原生App发起的网络请求其Referer通常是null或一个固定的包名标识不是HTTP协议标准行为。经过测试天地图API对移动端原生请求的Referer校验可能不生效或规则不同。最稳妥的办法是联系天地图的技术支持确认移动端SDK或API的具体校验规则。在未明确前可以尝试在申请时选择“移动端”应用类型如果有此选项或Referer留空进行测试。Unity实现注意在移动端使用UnityWebRequest是通用的。你也可以集成天地图官方或第三方提供的移动端SDK通常是Android/iOS原生库然后通过Unity的插件机制如AndroidJavaClass、iOS Native Plugins进行调用。这种情况下密钥的配置可能需要在原生SDK的初始化代码中设置而不是在Unity C#脚本里。3.4 IP白名单的高级管理与安全建议CIDR格式的使用如果你有一组服务器例如一个集群它们在一个网段内如192.0.2.0/24使用CIDR格式可以一次性添加整个网段避免逐个添加IP的麻烦。计算CIDR需要一些网络知识可以借助在线的“IP子网计算器”工具。定期审计与更新对于生产环境定期如每季度检查控制台中的密钥使用情况调用量、错误率和IP白名单列表。及时移除不再使用的服务器IP。密钥轮换对于安全要求高的项目应制定密钥轮换策略。例如每年更新一次密钥。操作步骤是先在控制台创建新密钥并配置好白名单然后在你的应用配置中更新为新密钥验证无误后再在控制台禁用或删除旧密钥。确保新旧密钥有一小段重叠时间避免服务中断。分层防护不要依赖IP白名单作为唯一的安全措施。结合Referer限制、调用频率限制可在自己代理服务器实现、HTTPS加密传输构建多层次的安全防护。4. Unity中集成与调用的实战代码示例理论说再多不如一行代码。这里给出Unity中使用最基础的UnityWebRequest加载一个天地图矢量底图瓦片的示例并融入密钥管理和错误处理。假设我们已经有一个管理密钥的静态类TianDiTuConfig。using UnityEngine; using UnityEngine.Networking; using System.Collections; using System.Text; public class TianDiTuMapLoader : MonoBehaviour { // 示例天地图矢量底图URL模板 (需替换为自己的图层类型和参数) private string tileUrlTemplate https://t{0-3}.tianditu.gov.cn/vec_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tkYOUR_KEY_HERE; public string layerType vec; // vec:矢量, cva:矢量注记, img:影像, cia:影像注记 public int zoomLevel 10; public int tileX 100; public int tileY 50; IEnumerator Start() { // 1. 构建请求URL (安全起见密钥应从配置处获取) string apiKey TianDiTuConfig.Instance.ApiKey; // 你的密钥管理类 if (string.IsNullOrEmpty(apiKey)) { Debug.LogError(天地图API密钥未配置请在TianDiTuConfig中设置。); yield break; } // 替换URL模板中的参数 string url tileUrlTemplate .Replace({z}, zoomLevel.ToString()) .Replace({x}, tileX.ToString()) .Replace({y}, tileY.ToString()) .Replace(YOUR_KEY_HERE, apiKey); // 2. 创建并发送UnityWebRequest using (UnityWebRequest request UnityWebRequestTexture.GetTexture(url)) { // 可以设置超时时间避免网络不佳时长时间卡住 request.timeout 10; yield return request.SendWebRequest(); // 3. 处理响应 if (request.result UnityWebRequest.Result.Success) { Texture2D tileTexture DownloadHandlerTexture.GetContent(request); // 在这里将纹理应用到你的地图瓦片Mesh或RawImage上 Debug.Log($成功加载天地图瓦片 ({tileX}, {tileY}) at z{zoomLevel}); // GetComponentRenderer().material.mainTexture tileTexture; } else { // 4. 详细的错误处理 Debug.LogError($天地图请求失败: {request.error}); Debug.LogError($响应码: {request.responseCode}); Debug.LogError($URL: {url}); // 解析天地图常见的错误响应通常是JSON或XML string errorBody request.downloadHandler?.text; if (!string.IsNullOrEmpty(errorBody)) { Debug.LogError($错误信息: {errorBody}); // 可以尝试解析错误体提取错误码如 statusCode: 1001 } // 根据错误类型给出提示 switch (request.result) { case UnityWebRequest.Result.ConnectionError: Debug.LogError(网络连接错误请检查网络。); break; case UnityWebRequest.Result.ProtocolError: if (request.responseCode 403) { Debug.LogError(访问被拒绝(403)。请检查1. API密钥是否正确且未过期。2. IP白名单或Referer设置是否允许当前环境。); } else if (request.responseCode 404) { Debug.LogError(资源未找到(404)。请检查瓦片坐标(z,x,y)是否在有效范围内。); } break; } } } } }代码关键点解析密钥管理绝对不要将密钥字符串硬编码在代码中。示例中通过一个配置类TianDiTuConfig获取这个类可以从Resources加载配置文件、从环境变量读取或使用Unity的PlayerSettings。URL构建天地图瓦片服务遵循WMTS或XYZ规范。你需要根据官方文档替换正确的图层类型(LAYER)、样式(STYLE)、瓦片矩阵集(TILEMATRIXSET)等参数。{z}/{x}/{y}是常见的瓦片坐标占位符。错误处理这是调试的关键。除了检查request.error一定要打印出responseCode和downloadHandler.text。天地图的错误信息通常会以JSON格式返回包含具体的错误码如1001代表密钥无效这对于定位白名单问题至关重要。WebGL注意事项在WebGL平台由于浏览器安全策略如果你请求的天地图域名如t*.tianditu.gov.cn与你部署的域名不同就会遇到CORS错误。控制台会明确提示。这就是为什么之前强烈推荐使用服务器代理方案的根本原因因为它将请求变为“同源请求”完美规避CORS。5. 常见问题排查与实战调试技巧即使按照指南配置在实际集成中仍可能遇到问题。下面是一个快速排查清单和实战调试技巧。5.1 问题排查清单现象可能原因排查步骤编辑器测试正常打包后WebGL/移动端不显示地图。1. 密钥的IP白名单限制了开发机IP未允许用户IP。2. WebGL的CORS问题。3. 移动端Referer校验失败。1. 检查生产环境密钥的IP白名单设置是否留空或包含代理服务器IP。2. WebGL打开浏览器开发者工具F12查看“网络(Network)”标签确认请求是否发出响应状态码是403还是CORS错误。3. 移动端抓包或输出日志查看请求详情。控制台报错{“statusCode”:”1001”}API密钥无效。1. 检查URL中tk参数后的密钥字符串是否完整、无多余空格。2. 登录天地图控制台确认该密钥是否被禁用或删除。3. 确认使用的密钥类型浏览器端/服务器端与应用场景是否匹配。控制台报错{“statusCode”:”1002”}IP或Referer不在白名单内。1.对于IP问题确认发出请求的机器的公网IP是什么并与控制台白名单对比。如果是客户端直连IP白名单应留空。2.对于Referer问题检查请求的HTTP头中的Referer值。在浏览器开发者工具的“网络”标签中查看请求头。确认该值是否在你设置的白名单域名规则内。本地file://协议Referer为空。WebGL在本地文件打开时一片空白浏览器控制台报CORS错误。跨域资源共享策略阻止。1. 使用本地HTTP服务器如python -m http.server运行WebGL构建文件。2. 或者采用服务器代理模式从根本上解决CORS问题。地图能显示但加载很慢或有部分瓦片缺失。1. 网络问题。2. 瓦片坐标计算错误请求了不存在的层级或范围。3. 天地图服务限流。1. 检查网络连接。2. 调试输出瓦片的z/x/y坐标确保其在有效范围内例如天地图矢量底图最大层级一般为18。3. 如果是高频请求考虑在客户端或代理服务器增加瓦片缓存机制。在Unity中UnityWebRequest状态是Result.ProtocolError响应码403。访问被拒绝。综合了密钥、IP、Referer等多种可能。1. 这是最常见的问题。按照上述1001和1002的错误排查逻辑进行。2.终极调试法将失败的完整URL包含密钥复制出来直接粘贴到浏览器的地址栏中访问。观察返回的信息。如果浏览器能显示图片说明问题可能出在Unity的请求头或环境上如果浏览器也返回错误JSON那问题一定在密钥或白名单配置上根据浏览器返回的JSON错误码精准定位。5.2 实战调试技巧浏览器开发者工具是你的好朋友无论是测试WebGL还是分析普通网页请求一定要打开浏览器的开发者工具F12。重点关注“网络(Network)”标签页。这里能看到每一个请求的详细信息URL、请求头Request Headers、响应状态码Status、响应头Response Headers和响应体Response。天地图的错误信息就在响应体里。对比验证法当你的Unity应用请求失败时手动构建一个你认为正确的天地图瓦片URL可以在网上找一些在线的天地图URL示例替换上你的密钥和坐标直接放到浏览器里访问。如果浏览器能成功显示图片说明你的密钥和白名单配置本身是正确的问题出在Unity发出请求的方式或环境上比如CORS、请求头缺失。如果浏览器也失败那就集中精力检查控制台配置。分阶段测试法不要一次性把所有功能都做完再测试地图。应该先做一个最简单的测试场景一个空场景一个脚本只请求一张固定的、已知有效的瓦片比如北京中心区域z10, xxxx, yxxx。用这个最简案例验证你的密钥、网络、基础代码是否畅通。通了之后再接入复杂的地图渲染逻辑。日志记录要详尽在你的Unity代码中在发起请求前将完整的请求URL打印到日志或控制台。这个URL包含了所有参数和你的密钥注意在生产环境日志中要对密钥部分打码。当出现问题时这个完整的URL是复现和排查问题的黄金信息。最后关于“天地图创建后如何销毁”这个热词在Unity上下文中通常指的是释放地图资源以避免内存泄漏。如果你使用的是动态加载的Texture瓦片在不需要时如场景切换、地图关闭记得调用Destroy(tileTexture)或Resources.UnloadAsset。如果使用了第三方地图插件查阅其API通常会有Dispose(),DestroyMap(),Clear()之类的方法来清理内部对象和缓存。
1. 项目概述为什么Unity开发者需要关注天地图API如果你正在用Unity开发涉及地图、位置服务或地理信息可视化的项目无论是智慧城市、物流仿真、文旅导览还是游戏中的真实世界场景那么“天地图”这个名字你一定不陌生。作为国内权威的地理信息服务它提供了包括矢量、影像、地形在内的多种底图服务数据权威、更新及时且对开发者相对友好。但很多Unity开发者在接入时第一步——申请API密钥和配置IP白名单——就卡住了要么是流程不熟要么是配置后服务依然无法调用尤其是在WebGL平台或服务器部署时问题频发。我自己在多个商业项目中集成过天地图从PC端应用到移动端App再到WebGL的网页应用几乎把所有能踩的坑都踩了一遍。我发现网上很多教程只讲了“点击这里、填写那里”的步骤却没说清楚背后的逻辑比如“应用类型”到底怎么选、“安全设置”里的IP白名单有什么门道、为什么在Unity编辑器里测试正常一打包发布就报“您的密钥无效”。这导致开发者照着做也未必能成功反复折腾浪费大量时间。这篇文章我就以一个Unity老鸟的身份带你彻底搞懂天地图API密钥从申请到安全配置的全过程。目标很明确5分钟完成申请是基础更重要的是让你理解每一个配置项的意义掌握IP白名单设置的核心理念和技巧确保你的密钥在开发、测试、生产全生命周期中都安全、稳定、可用。我们会结合Unity开发中常见的场景特别是WebGL这个“老大难”平台把那些官方文档里没写、但实践中至关重要的细节掰开揉碎讲清楚。2. 天地图API密钥申请全流程拆解与避坑指南申请一个天地图API密钥表面上看就是在官网上填个表单但里面的每一个选项都直接关系到你后续开发的顺畅程度。很多人申请时随便一填到了用的时候才发现各种限制回头重新申请反而更麻烦。2.1 前期准备与平台选择首先访问“国家地理信息公共服务平台”俗称天地图官网。你需要注册一个个人或企业账号。这里有个小建议如果是商业项目强烈建议使用企业身份注册和申请。个人账号虽然快捷但在调用量配额、服务稳定性支持以及未来可能涉及的法律合规性上企业账号更有保障。注册过程按部就班即可需要手机号和邮箱验证。登录后进入“控制台”或“我的密钥”页面开始创建应用。第一个关键选择来了“应用类型”。这里通常有“浏览器端”、“服务器端”、“移动端”等选项。Unity编辑器内测试与PC/Mac独立平台这属于浏览器端吗严格来说Unity编辑器本身和打包后的桌面应用.exe, .app并非通过浏览器运行。但是天地图的“浏览器端”密钥校验机制通常是基于HTTP Referer请求来源或IP。在本地运行时这些信息可能为空或不固定。经过实测对于在本地localhost环境或本地文件系统file://中测试的Unity项目包括编辑器Play模式选择“浏览器端”并做特殊配置后面IP白名单会讲通常是可行的。但更稳妥的做法是如果应用最终是桌面端且不需要从公网访问天地图服务可以优先考虑是否需要API密钥某些本地化部署方案可能通过其他方式解决。Unity WebGL平台这是绝对的重灾区必须选择“浏览器端”。因为WebGL应用最终是运行在用户的浏览器中的所有对天地图服务的请求都是从最终用户的IP发出的。这是理解后续所有配置的基石。移动端iOS/Android如果您的Unity应用打包成手机App情况类似WebGL。虽然它是一个原生应用但其中用于显示地图的WebView或网络请求源头是用户设备的IP。因此通常也建议选择“浏览器端”并配合动态IP策略即不设IP白名单但启用其他安全措施。少数需要服务器中转地图瓦片的情况除外。服务端调用如果你的Unity项目有一个后端服务器需要服务器去请求天地图的数据然后处理后再发给客户端那么你必须额外申请一个“服务器端”密钥。这个密钥的校验是基于服务器公网IP的。避坑心得1我的建议是为不同的运行环境创建不同的密钥。例如单独为“WebGL测试环境”创建一个浏览器端密钥为“生产环境服务器”创建一个服务器端密钥。这样做的好处是权限隔离即使测试密钥泄露也不会影响线上服务同时也方便对不同密钥的调用量进行独立监控和管理。2.2 关键信息填写与“安全设置”深度解析创建应用时你需要填写应用名称、描述等信息这些按实填写即可。核心在于“安全设置”部分这里直接决定了你的密钥能否被成功调用。安全设置主要包含两大块Referer白名单和IP白名单。对于Unity开发者而言IP白名单是重中之重也是困惑最多的地方。Referer请求来源白名单是什么HTTP请求头中的一个字段用来告诉服务器这个请求是从哪个页面链接过来的。主要用于保护网页应用。Unity相关场景对于WebGL应用如果你的游戏页面部署在https://yourgame.com那么你可以将https://yourgame.com/*加入Referer白名单。这样只有从这个域名下发出的请求才会被天地图服务器认可。怎么填支持通配符*。例如https://localhost:*表示允许所有本地localhost端口用于开发测试。https://*.yourcompany.com/*表示允许公司所有子域名。重要限制很多开发者不知道Referer校验在本地文件file://协议和某些严格的安全环境下可能为空或被浏览器禁止发送。这意味着如果你直接用浏览器打开本地的WebGL构建的HTML文件Referer是空的会导致校验失败。这是本地测试常见的一个坑。IP白名单是什么允许访问天地图服务的服务器或客户端的公网IP地址列表。这是比Referer更常用、也更关键的防护手段。Unity核心难题Unity应用运行环境的IP是不确定的。编辑器/PC端开发者的机器IP可能是家庭或公司的动态IP。WebGL用户遍布全球IP千变万化。移动端用户使用4G/5G或不同Wi-FiIP随时在变。策略选择情况A需要固定服务器IP中转。这是最推荐给WebGL和移动端的生产环境方案。你不直接让客户端请求天地图而是在你的服务器上写一个代理接口。客户端请求你的服务器你的服务器使用服务器端密钥再去请求天地图然后将数据返回给客户端。此时你只需要在服务器端密钥的IP白名单中填入你服务器的公网IP即可。客户端密钥浏览器端的IP白名单可以留空或填写0.0.0.0/0允许所有IP但需配合Referer等其他限制。情况B客户端直连且用户IP不确定。对于测试、演示或用户量可控的内部项目你可能不得不让客户端直连。这时IP白名单必须留空。留空意味着“不启用IP白名单校验”天地图仅通过密钥本身来验证。这是一个极其重要的技巧很多开发者误以为必须填个IP结果填了自家IP导致其他用户无法使用。情况C开发测试环境。如果你希望在办公室或家里固定IP的环境下测试客户端直连可以将你的当前公网IP填入。但注意家庭宽带IP可能会重启变化公司网络可能出口IP不止一个。避坑心得2在控制台填写IP白名单时天地图支持两种格式单个IP如123.123.123.123和CIDR格式网段如123.123.123.0/24。如果你使用云服务器务必在服务器控制台查看其公网IP而不是内网IP。一个快速获取本机公网IP的方法是打开浏览器搜索“我的IP”。2.3 申请完成后的关键动作提交申请后通常很快就能获得一串密钥一串字符串。拿到密钥后不要急着把它硬编码到你的Unity脚本里。你应该立刻做以下几件事环境变量管理将密钥存储在Unity的PlayerSettings中作为一个自定义脚本定义符号或者使用一个不提交到版本库的配置文件如Resources目录下的一个加密文本或通过Unity的Cloud Config。绝对不要将密钥明文上传到Git等公共仓库。立即进行最小化测试写一个最简单的脚本在Start函数里用UnityWebRequest去请求一个天地图最简单的瓦片URL并把你的密钥作为参数拼接上去。在编辑器里运行查看控制台日志。如果返回错误信息可以根据错误码如1001代表密钥错误1002代表IP或Referer不允许快速定位是密钥问题还是安全设置问题。记录密钥与应用的对应关系在项目文档或密码管理工具中清晰记录这个密钥对应的应用名称、平台WebGL/移动端、安全设置IP白名单规则方便日后维护和轮换。3. IP白名单设置的核心技巧与多场景实战理解了IP白名单的原理后我们来针对Unity开发中最典型的几个场景给出具体的配置方案和技巧。3.1 场景一Unity编辑器与PC独立平台开发测试目标在Unity编辑器的Play模式以及打包出的PC/Mac独立应用中能正常加载天地图。挑战应用运行在本机其网络请求出口IP是你机器的公网IP。家庭宽带IP常变公司网络可能有统一出口代理IP相对固定但可能多个。配置方案为这个测试环境单独申请一个“浏览器端”密钥。IP白名单填入你当前开发机的公网IP。如果你在公司需要询问运维人员公司的外网出口IP段并可能需要用CIDR格式如202.120.10.0/24来覆盖整个办公网段。Referer白名单留空或填写http://localhost:*和file://*如果支持。注意并非所有地图API SDK都支持file://协议。实操技巧写一个小的编辑器工具脚本定期比如每天启动Unity时调用一个IP查询接口获取本机公网IP并提示开发者是否需要更新控制台的白名单。这能应对家庭IP变化的问题。如果公司网络复杂可以尝试在测试阶段暂时清空IP白名单完成基本功能测试。但上线前必须确定最终的网络架构。3.2 场景二Unity WebGL平台最复杂场景目标将Unity项目构建为WebGL并部署到服务器后用户通过浏览器能正常看到天地图。挑战用户IP未知且动态浏览器安全策略CORS限制本地file://协议测试困难。推荐配置方案生产环境最佳实践架构采用“客户端 - 你的服务器 - 天地图”的代理模式。密钥配置客户端浏览器端密钥申请一个其IP白名单留空。Referer白名单填写你的网站域名例如https://game.yourdomain.com/*。这个密钥实际上可能只用于一些不需要IP校验的轻量级服务或者干脆不用。核心的地图瓦片请求不走这个密钥。服务器端服务器端密钥申请一个其IP白名单严格填写你的应用服务器公网IP。这个密钥用于你的服务器代理程序去合法地获取天地图数据。Unity中的实现你不能直接使用天地图的瓦片URL模板。你需要编写一个简单的后端服务可以用Node.js、Python Flask、C# ASP.NET Core等接收客户端传来的地图瓦片坐标z, x, y或范围参数然后用服务器端密钥向天地图发起请求获取到图片数据后再返回给客户端的Unity WebGL应用。优势安全你的服务器端密钥IP固定非常安全。客户端密钥即使暴露攻击者也无法直接高频率调用天地图受你服务器代理的逻辑控制。可控可以在服务器端加入缓存、限流、日志监控。绕过CORS服务器代理天然解决了浏览器跨域问题。备选方案仅用于演示或低频内部应用如果必须客户端直连则申请一个“浏览器端”密钥。IP白名单留空。Referer白名单必须严格设置为你部署的域名例如https://demo.yourdomain.com/*。这能提供最基本的一层防护。在Unity中使用UnityWebRequest或相关地图插件如Mapbox Unity SDK的适配层发起请求。避坑心得3WebGL本地测试。这是个大坑。如果你用浏览器直接打开本地构建的index.htmlfile://协议由于安全限制UnityWebRequest可能无法正常工作且Referer为空。解决方案有使用一个简单的本地HTTP服务器来托管你的WebGL构建文件。例如在构建目录下运行python -m http.server 8000然后通过http://localhost:8000访问。这样就有了一个合法的本地域名和Referer。在Unity的Player Settings - WebGL - Publishing Settings中可以尝试调整“WebGL模板”或启用“Development Build”来获得更详细的错误信息。3.3 场景三iOS/Android移动端平台目标打包后的移动App能显示天地图。挑战移动网络4G/5G和不同Wi-Fi下的IP动态变化App内WebView或网络请求的标识。配置方案方案A类似WebGL代理推荐为移动App配备一个后端服务器所有地图请求通过你的服务器代理转发。配置同上文WebGL最佳实践。这是最安全、最可控的方式尤其适合需要展示大量地图数据或进行地理计算的商业应用。方案B客户端直连申请“浏览器端”密钥。IP白名单留空。Referer白名单如何处理移动端原生App发起的网络请求其Referer通常是null或一个固定的包名标识不是HTTP协议标准行为。经过测试天地图API对移动端原生请求的Referer校验可能不生效或规则不同。最稳妥的办法是联系天地图的技术支持确认移动端SDK或API的具体校验规则。在未明确前可以尝试在申请时选择“移动端”应用类型如果有此选项或Referer留空进行测试。Unity实现注意在移动端使用UnityWebRequest是通用的。你也可以集成天地图官方或第三方提供的移动端SDK通常是Android/iOS原生库然后通过Unity的插件机制如AndroidJavaClass、iOS Native Plugins进行调用。这种情况下密钥的配置可能需要在原生SDK的初始化代码中设置而不是在Unity C#脚本里。3.4 IP白名单的高级管理与安全建议CIDR格式的使用如果你有一组服务器例如一个集群它们在一个网段内如192.0.2.0/24使用CIDR格式可以一次性添加整个网段避免逐个添加IP的麻烦。计算CIDR需要一些网络知识可以借助在线的“IP子网计算器”工具。定期审计与更新对于生产环境定期如每季度检查控制台中的密钥使用情况调用量、错误率和IP白名单列表。及时移除不再使用的服务器IP。密钥轮换对于安全要求高的项目应制定密钥轮换策略。例如每年更新一次密钥。操作步骤是先在控制台创建新密钥并配置好白名单然后在你的应用配置中更新为新密钥验证无误后再在控制台禁用或删除旧密钥。确保新旧密钥有一小段重叠时间避免服务中断。分层防护不要依赖IP白名单作为唯一的安全措施。结合Referer限制、调用频率限制可在自己代理服务器实现、HTTPS加密传输构建多层次的安全防护。4. Unity中集成与调用的实战代码示例理论说再多不如一行代码。这里给出Unity中使用最基础的UnityWebRequest加载一个天地图矢量底图瓦片的示例并融入密钥管理和错误处理。假设我们已经有一个管理密钥的静态类TianDiTuConfig。using UnityEngine; using UnityEngine.Networking; using System.Collections; using System.Text; public class TianDiTuMapLoader : MonoBehaviour { // 示例天地图矢量底图URL模板 (需替换为自己的图层类型和参数) private string tileUrlTemplate https://t{0-3}.tianditu.gov.cn/vec_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tkYOUR_KEY_HERE; public string layerType vec; // vec:矢量, cva:矢量注记, img:影像, cia:影像注记 public int zoomLevel 10; public int tileX 100; public int tileY 50; IEnumerator Start() { // 1. 构建请求URL (安全起见密钥应从配置处获取) string apiKey TianDiTuConfig.Instance.ApiKey; // 你的密钥管理类 if (string.IsNullOrEmpty(apiKey)) { Debug.LogError(天地图API密钥未配置请在TianDiTuConfig中设置。); yield break; } // 替换URL模板中的参数 string url tileUrlTemplate .Replace({z}, zoomLevel.ToString()) .Replace({x}, tileX.ToString()) .Replace({y}, tileY.ToString()) .Replace(YOUR_KEY_HERE, apiKey); // 2. 创建并发送UnityWebRequest using (UnityWebRequest request UnityWebRequestTexture.GetTexture(url)) { // 可以设置超时时间避免网络不佳时长时间卡住 request.timeout 10; yield return request.SendWebRequest(); // 3. 处理响应 if (request.result UnityWebRequest.Result.Success) { Texture2D tileTexture DownloadHandlerTexture.GetContent(request); // 在这里将纹理应用到你的地图瓦片Mesh或RawImage上 Debug.Log($成功加载天地图瓦片 ({tileX}, {tileY}) at z{zoomLevel}); // GetComponentRenderer().material.mainTexture tileTexture; } else { // 4. 详细的错误处理 Debug.LogError($天地图请求失败: {request.error}); Debug.LogError($响应码: {request.responseCode}); Debug.LogError($URL: {url}); // 解析天地图常见的错误响应通常是JSON或XML string errorBody request.downloadHandler?.text; if (!string.IsNullOrEmpty(errorBody)) { Debug.LogError($错误信息: {errorBody}); // 可以尝试解析错误体提取错误码如 statusCode: 1001 } // 根据错误类型给出提示 switch (request.result) { case UnityWebRequest.Result.ConnectionError: Debug.LogError(网络连接错误请检查网络。); break; case UnityWebRequest.Result.ProtocolError: if (request.responseCode 403) { Debug.LogError(访问被拒绝(403)。请检查1. API密钥是否正确且未过期。2. IP白名单或Referer设置是否允许当前环境。); } else if (request.responseCode 404) { Debug.LogError(资源未找到(404)。请检查瓦片坐标(z,x,y)是否在有效范围内。); } break; } } } } }代码关键点解析密钥管理绝对不要将密钥字符串硬编码在代码中。示例中通过一个配置类TianDiTuConfig获取这个类可以从Resources加载配置文件、从环境变量读取或使用Unity的PlayerSettings。URL构建天地图瓦片服务遵循WMTS或XYZ规范。你需要根据官方文档替换正确的图层类型(LAYER)、样式(STYLE)、瓦片矩阵集(TILEMATRIXSET)等参数。{z}/{x}/{y}是常见的瓦片坐标占位符。错误处理这是调试的关键。除了检查request.error一定要打印出responseCode和downloadHandler.text。天地图的错误信息通常会以JSON格式返回包含具体的错误码如1001代表密钥无效这对于定位白名单问题至关重要。WebGL注意事项在WebGL平台由于浏览器安全策略如果你请求的天地图域名如t*.tianditu.gov.cn与你部署的域名不同就会遇到CORS错误。控制台会明确提示。这就是为什么之前强烈推荐使用服务器代理方案的根本原因因为它将请求变为“同源请求”完美规避CORS。5. 常见问题排查与实战调试技巧即使按照指南配置在实际集成中仍可能遇到问题。下面是一个快速排查清单和实战调试技巧。5.1 问题排查清单现象可能原因排查步骤编辑器测试正常打包后WebGL/移动端不显示地图。1. 密钥的IP白名单限制了开发机IP未允许用户IP。2. WebGL的CORS问题。3. 移动端Referer校验失败。1. 检查生产环境密钥的IP白名单设置是否留空或包含代理服务器IP。2. WebGL打开浏览器开发者工具F12查看“网络(Network)”标签确认请求是否发出响应状态码是403还是CORS错误。3. 移动端抓包或输出日志查看请求详情。控制台报错{“statusCode”:”1001”}API密钥无效。1. 检查URL中tk参数后的密钥字符串是否完整、无多余空格。2. 登录天地图控制台确认该密钥是否被禁用或删除。3. 确认使用的密钥类型浏览器端/服务器端与应用场景是否匹配。控制台报错{“statusCode”:”1002”}IP或Referer不在白名单内。1.对于IP问题确认发出请求的机器的公网IP是什么并与控制台白名单对比。如果是客户端直连IP白名单应留空。2.对于Referer问题检查请求的HTTP头中的Referer值。在浏览器开发者工具的“网络”标签中查看请求头。确认该值是否在你设置的白名单域名规则内。本地file://协议Referer为空。WebGL在本地文件打开时一片空白浏览器控制台报CORS错误。跨域资源共享策略阻止。1. 使用本地HTTP服务器如python -m http.server运行WebGL构建文件。2. 或者采用服务器代理模式从根本上解决CORS问题。地图能显示但加载很慢或有部分瓦片缺失。1. 网络问题。2. 瓦片坐标计算错误请求了不存在的层级或范围。3. 天地图服务限流。1. 检查网络连接。2. 调试输出瓦片的z/x/y坐标确保其在有效范围内例如天地图矢量底图最大层级一般为18。3. 如果是高频请求考虑在客户端或代理服务器增加瓦片缓存机制。在Unity中UnityWebRequest状态是Result.ProtocolError响应码403。访问被拒绝。综合了密钥、IP、Referer等多种可能。1. 这是最常见的问题。按照上述1001和1002的错误排查逻辑进行。2.终极调试法将失败的完整URL包含密钥复制出来直接粘贴到浏览器的地址栏中访问。观察返回的信息。如果浏览器能显示图片说明问题可能出在Unity的请求头或环境上如果浏览器也返回错误JSON那问题一定在密钥或白名单配置上根据浏览器返回的JSON错误码精准定位。5.2 实战调试技巧浏览器开发者工具是你的好朋友无论是测试WebGL还是分析普通网页请求一定要打开浏览器的开发者工具F12。重点关注“网络(Network)”标签页。这里能看到每一个请求的详细信息URL、请求头Request Headers、响应状态码Status、响应头Response Headers和响应体Response。天地图的错误信息就在响应体里。对比验证法当你的Unity应用请求失败时手动构建一个你认为正确的天地图瓦片URL可以在网上找一些在线的天地图URL示例替换上你的密钥和坐标直接放到浏览器里访问。如果浏览器能成功显示图片说明你的密钥和白名单配置本身是正确的问题出在Unity发出请求的方式或环境上比如CORS、请求头缺失。如果浏览器也失败那就集中精力检查控制台配置。分阶段测试法不要一次性把所有功能都做完再测试地图。应该先做一个最简单的测试场景一个空场景一个脚本只请求一张固定的、已知有效的瓦片比如北京中心区域z10, xxxx, yxxx。用这个最简案例验证你的密钥、网络、基础代码是否畅通。通了之后再接入复杂的地图渲染逻辑。日志记录要详尽在你的Unity代码中在发起请求前将完整的请求URL打印到日志或控制台。这个URL包含了所有参数和你的密钥注意在生产环境日志中要对密钥部分打码。当出现问题时这个完整的URL是复现和排查问题的黄金信息。最后关于“天地图创建后如何销毁”这个热词在Unity上下文中通常指的是释放地图资源以避免内存泄漏。如果你使用的是动态加载的Texture瓦片在不需要时如场景切换、地图关闭记得调用Destroy(tileTexture)或Resources.UnloadAsset。如果使用了第三方地图插件查阅其API通常会有Dispose(),DestroyMap(),Clear()之类的方法来清理内部对象和缓存。
