从ArcGIS Enterprise部署完那一刻起底图问题就是绕不开的一道坎。Portal自带的底图库只有Esri系列很多人想用国产的天地图作为底图结果卡在这几个地方不知道去哪申请密钥tk、不知道填什么服务地址、在Portal底图库里加WMTS又找不到对应的配置项。这篇文章就把完整流程拆开来讲包括天地图服务地址的申请与解析、Portal底图库的工作原理、具体的添加步骤以及我在实际项目里踩过的坑和排查思路。适合GIS管理员、ArcGIS二次开发工程师以及刚接手Portal运维、想切换国产底图的测绘行业朋友。1. 天地图服务申请与WMTS地址解析1.1 申请开发者密钥天地图的所有在线服务都要求带上一个tk参数即token/密钥这是很多人的第一个坎。打开天地图官网的开发者页面注册一个账号然后创建“应用”申请一个服务密钥。这里要注意的是天地图区分“浏览器端密钥”和“服务端密钥”通常用在ArcGIS Portal里的是服务端密钥也就是在服务器端调用WMTS/WMS服务时使用的那个tk。密钥申请下来之后天地图会给你一个形如xxxxxxxxxxxxxxxx的字符串。这个tk后面会拼到每一个瓦片请求的URL上所以不要把它写死在业务系统前端尽量放在服务端或者Portal的配置里统一管理。虽然天地图目前对个人开发者申请密钥比较宽松但生产环境里建议申请企业级认证或商用授权避免流量超限被断服。1.2 WMTS服务地址结构拆解天地图提供的主要底图类型有矢量vec、矢量注记cva、影像img、影像注记cia、地形ter、地形注记cta每一类对应一套WMTS服务。WMTS地址的一般格式是https://t0.tianditu.gov.cn/vec_wmts?servicewmtsrequestGetCapabilitiestk你的密钥其中t0可以是t0到t7这是天地图的地理负载均衡节点任意一个都能用建议在Portal里配一个主节点挂了再换另一个。把上面的地址里的vec_wmts换成img_wmts、ter_wmts等就是对应的影像、地形服务。这里有一个特别容易搞混的点天地图WMTS服务还分两个坐标系版本一个是默认的wmts对应EPSG:4326CGCS2000经纬度另一个是wmts-c对应EPSG:3857Web Mercator投影。如果是在Portal的Web地图里用绝大多数情况要选wmts-c版本否则地图投影和比例尺缩放会很别扭。举个例子https://t0.tianditu.gov.cn/vec_wmts?servicewmtsrequestGetCapabilitiestk你的密钥 // EPSG:4326 https://t0.tianditu.gov.cn/vec_wmts?servicewmtsrequestGetCapabilitiestk你的密钥layervec // 加了layer参数指定图层严格来说天地图的vec_wmts服务能力文档里会同时列出多个TileMatrixSet包括EPSG:4326_Scale、EPSG:3857_Scale等。你在配置Portal时要手动指定“坐标参考系”或“瓦片矩阵集”这一步选错就会导致地图空白或者只显示某一级别。1.3 用GetCapabilities文档验证服务地址在把地址填到Portal之前建议先在浏览器里打开一次GetCapabilities请求确认服务是通的、图层名没写错。这一步能省下后面大半的排查时间。https://t0.tianditu.gov.cn/vec_wmts?servicewmtsrequestGetCapabilitiestk你的密钥正常情况下你会看到一长串XML里面有Contents节点能看到Layer的Identifier比如vec以及TileMatrixSet的列表。如果浏览器返回的是JSON格式的错误信息或者提示tk验证失败那就是密钥问题如果返回404那就是图层名或服务路径写错了。实测下来ArcGIS对WMTS能力文档的解析比较严格需要确保能力文档里的TileMatrixSet定义完整尤其是ScaleDenominator和TopLeftCorner字段缺了任何一个Portal里都可能识别不到这个WMTS服务。2. Portal底图库工作原理与添加路径2.1 底图库到底是什么Portal里的“底图库”不是一个文件目录而是一个组织级的配置项。它存储的是当前Portal组织里所有可用的底图定义包括底图名称、服务地址、图层类型、缩略图等元信息。当用户新建Web地图时点“底图”按钮弹出的底图选择器会读取这个配置把底图列表展示出来。换句话说“往Portal里加天地图”的本质就是往这个配置项里注册一条新的底图记录。这个配置在ArcGIS Enterprise 10.7之前叫“底图库”在10.7及之后的新版Portal里管理路径变成了“组织 → 设置 → 地图”然后在“底图”区域里管理。新版界面里你还可以直接给底图配置缩略图URL更方便。2.2 两条添加路径底图库配置与直接加载外部服务在Portal里加载天地图按入口分主要两条路第一条是走“底图库管理”把天地图注册成底图之后所有Web地图都能一键切换。第二条是在单个Web地图或Web AppBuilder里通过“添加图层”直接加载WMTS/WMS服务。对于大多数项目我更推荐第一条因为它能实现组织内统一管理不需要每个地图单独配一遍。不过要注意底图库配置里能添加的服务类型是有限制的早期的Portal底图库只支持ArcGIS动态地图服务、切片地图服务、WMS和WMTS。近年版本支持的OGC服务类型更丰富一些但天地图用WMTS标准接入是兼容性最好、最不容易出幺蛾子的方式。2.3 Portal访问远程服务的网络前提这里有一个很多人忽略的前提Portal服务器本体必须能访问t0.tianditu.gov.cn这个域名。如果你把Portal部署在内网机器只能出外网但需要走代理那必须在服务器上配置好系统代理或者用IIS/nginx做一层反向代理把天地图的请求转发出去。否则配置底图时可以正常填地址但Web地图里加载时会一直转圈最后显示空白。另外新版ArcGIS Enterprise对HTTPS比较敏感。如果用HTTP访问天地图的WMTS而Portal的WebAdaptor配置的是HTTPS安全协议混用可能会导致浏览器直接拦截混合内容。这时候可以优先使用天地图的HTTPS地址实测都能正常支持。3. 在Portal底图库中添加天地图WMTS实操3.1 进入底图库管理界面我以ArcGIS Enterprise 10.9/11.x的Portal为例。用管理员账号登录Portal点右上角“组织”进入“设置”找到“地图”这一栏旧版叫“底图”。这里你会看到当前基线底图库的列表默认有“浅灰色画布”“矢量底图”“影像底图”等选项全部来自ArcGIS Online。我们要做的是在右侧点“添加底图”。这里需要注意一个权限问题只有组织的管理员或者拥有相应权限的成员才能修改底图库配置。如果是普通用户登录是看不到“添加底图”这个按钮的。3.2 添加WMTS服务的参数填写点击“添加底图”后会弹出一个对话框。名称随便填比如“天地图矢量底图”类型选择“OGC WMTS”。接下来是最关键的URL框填入前面验证过的那条GetCapabilities地址。https://t0.tianditu.gov.cn/vec_wmts?servicewmtsrequestGetCapabilitiestk你的密钥填完URL后点击“图层”旁边的刷新按钮Portal会自动解析能力文档列出可用的图层。这里你可能看到vec图层选择它。再往下是“格式”一般默认image/png或者image/jpeg天地图的矢量图层建议用PNG影像用JPEG就可以。接下来是瓦片矩阵集TileMatrixSet。这里务必选择EPSG:3857对应的那个一般是EPSG:3857_Scale不要选EPSG:4326_Scale。选错的话在Web地图里会导致天地图与Org底图或其他服务对不齐出现偏移。3.3 自定义参数的处理技巧如果Portal版本较老或者直接填上面那条含tk的GetCapabilities地址无法解析就用到自定义参数。在“自定义参数”栏里添加一行参数名填tk参数值填你的密钥。这样Portal在请求瓦片时会自动把tk追加到每个瓦片URL后面。有朋友会问“没有自定义参数栏怎么办”这个问题我后面第5章专门讲这里是提个醒10.7及以上版本里在图层选择下拉框旁边往往直接就有“自定义参数”的区域要是你的版本界面里确实没找到可能是你在“数据”页面添加的是WMS服务而不是WMTS先检查类型是否选对。3.4 保存并验证底图参数填完后最下面的“缩略图”可以留空也可以手动填一个天地图的预览图URL这样在底图选择器里更好看一点。点“保存”底图库里就多了一条“天地图矢量底图”。接下来新建一个Web地图在底图切换器里选它如果地图能正常放大缩小、拖拽不偏移就说明成功了。我在实际项目中还遇到过一个细节Portal底图库里添加WMTS底图后第一次打开Web地图时底图不显示但过几分钟又突然出来了。这往往不是服务问题而是Portal在缓存能力文档或瓦片尤其是内网访问海外服务时首次解析较慢耐心等一等或者按F5刷新。如果始终空白就把第4章的排查清单过一遍。3.5 顺带提一下ArcGIS Pro里的验证方式配置之前或排查问题时我建议先在ArcGIS Pro里验证一次天地图服务因为Pro的表单交互更直接能快速看出是服务问题还是Portal配置问题。打开Pro在“地图”选项卡下点“添加数据”选择“来自路径”粘贴WMTS地址。Pro会弹出一个WMTS服务属性框选择“图层”和“瓦片矩阵集”确定后就能加到地图里。这里的坐标参考系选择技巧和Portal里一样选EPSG:3857_Scale。Pro里加载成功之后再回Portal配置基本不会出问题。https://t0.tianditu.gov.cn/vec_wmts?servicewmtsrequestGetCapabilitiestk你的密钥4. QGIS、小程序与离线瓦片等扩展场景4.1 QGIS加载天地图的两种写法热词里出现了“qgis加载天地图”我顺带说一嘴因为很多人会在QGIS里先验证天地图能不能用再决定怎么给Portal配。QGIS里加载天地图可以走“数据源管理器 → WMS/WMTS”输入上面的GetCapabilities地址点“连接”加载图层。还有一种更简单的方式在QGIS里用“XYZ Tile”图层模板直接手填瓦片URL模板https://t0.tianditu.gov.cn/vec_wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETEPSG:3857FORMATimage/pngTILEMATRIX{z}TILEROW{y}TILECOL{x}tk你的密钥注意QGIS的XYZ图层里占位符是{z}/{x}/{y}但天地图的WMTS参数里TILEMATRIX、TILEROW、TILECOL分别对应级别、行、列所以上面模板里的TILEMATRIX{z}这种写法在QGIS里是可以识别的。这套模板同样可以用于其他支持XYZ模板的工具。4.2 微信小程序集成天地图的应用方向“天地图 集成 微信小程序”在热词里排得挺靠前这也是一类典型需求。小程序里没有桌面GIS那么复杂的SDK通常做法是小程序前端直接用wx.request请求天地图的WMTS瓦片地址再叠加一个自己画的marker层。底图瓦片的请求格式就是上面那段XYZ模板。这里有一个合规和稳定性的提醒小程序的域名白名单要求所有请求域名必须是HTTPS并且要预先在小程序后台配置。天地图的HTTPS域名t0.tianditu.gov.cn虽然在大部分情况下可以直连但生产环境建议用自己服务端做一次转发或代理一方面统一管理tk另一方面也避免小程序端直接暴露密钥。关于“天地图逆地址解析”的热词其实对应的是天地图Web服务API里的地理编码接口跟底图瓦片加载是两条线但在小程序里通常会一起用到先加载底图再根据经纬度调逆地址解析把坐标转成文字位置。4.3 离线瓦片下载与内网发布思路热词里还有一个“下载天地图离线瓦片”这通常是涉密内网或者无外网环境中GIS平台建设的老问题。这里必须强调天地图在线服务有其使用协议个人和企业项目在遵守协议的前提下可缓存使用但涉及成果版权和数据安全的问题务必提前确认授权边界。技术路径上可以用桌面端工具按行政区或矩形范围、按比例尺等级下载瓦片下载后再利用ArcGIS Pro的“创建缓存”或第三方切片工具把瓦片发布成ArcGIS切片服务发布到Portal里就可以在完全断网的环境下使用了。这个方案我自己在项目里试过核心是两个坑一是下载范围太大导致磁盘被撑爆建议按“省-市-县”分级切块每个块单独发布二是切片方案要和天地图原切片方案保持一致否则拼接出来会有接缝或者偏移。比较稳妥的做法是先加载WMTS服务然后用ArcGIS Pro里的“导出切片缓存”功能去按当前地图范围导出地图坐标系设成EPSG:3857这样缓存切片在Portal里调用时图层空间参考和比例尺会比较一致。5. 常见问题与排查技巧实录5.1 为什么没有“自定义参数栏”这是被问得最多的一个。很多人照着网上的教程去加天地图结果在Portal的“添加底图”界面里翻遍了也找不到“自定义参数栏”这几个字。我的排查经验是首先要看你的Portal版本10.7以后自定义参数的位置变了不再是一个独立的表单区域而是隐藏在“图层”下拉框和“WMTS选项”里。你需要先选择图层展开“WMTS服务选项”或“高级属性”里面才会出现类似“服务参数”或“自定义参数”的编辑框。另一种可能是你选的服务类型不是“OGC WMTS”而是“WMS”或“ArcGIS Server”。如果选了WMS自定义参数栏确实不会出现因为WMS服务不需要额外传tk到瓦片URL而是通过GetMap请求另外处理。解决办法是把服务类型改回WMTS。5.2 添加后底图空白或一直转圈这种情况分几类原因。第一类tk错误或过期最典型的现象是页面只有地图控件但没有任何瓦片加载打开浏览器F12看网络请求会发现瓦片URL返回的是tk已过期或INVALID_TOKEN之类的JSON。第二类瓦片矩阵集选错底图加载出来但是完全错位或者是白屏这在第3.2节已经强调过。第三类网络不通比如服务器无法访问天地图域名这在2.3节也提过。排查顺序我总结了一个口诀先浏览器开GetCapabilities再QGIS/Pro直接加载最后回Portal里看F12。哪一步能成功就说明问题出在下一步。5.3 坐标偏移现象与坐标系选择天地图基于CGCS2000坐标系与WGS84在理论上是椭球参数略有不同但实际显示层面如果不做任何动态投影往往会有几米到十几米的偏移。在Portal Web地图场景里底图本身是EPSG:3857的WMTS-C服务和ArcGIS的Web Mercator接近整体偏差不大。但如果你叠加了CGCS2000或WGS84的矢量要素服务还可能出现“底图对不上”的情况。这种情况我建议把Web地图的坐标系显式设置为EPSG:3857并在矢量服务发布时也采用相同坐标系尽量避免在客户端做动态转换。如果项目硬性要求CGCS2000那就统一用天地图的EPSG:4326WMTS服务同时你的数据源也必须统一到CGCS2000全程一个坐标系不要混着用。5.4 反向代理与特殊网络环境下的配置在内网环境有时候服务器无法直接访问天地图但用户电脑能访问。这种时候给Portal配反向代理是最干净的方案。以nginx为例把天地图的t0.tianditu.gov.cn反代成内网地址map.xxx.local/tianditu然后Portal底图库里填的GetCapabilities地址就换成内网地址。注意HTML页面里返回的WMTS能力文档内部包含的图层URL如果还是指向t0.tianditu.gov.cn就必须改成相对路径或内网域名否则Portal解析完能力文档后实际请求瓦片还是会走外网。这一步很关键我在一个电力内网项目里就是被这个“能力文档里的绝对路径”卡了两天才排查出来。5.5 关于“ebmap 天地图坐标拾取”等衍生问题热词里的“ebmap 天地图坐标拾取”其实是要用地图坐标拾取工具来获取点位坐标。天地图坐标拾取器是一个网页工具能直接返回经纬度很多做数据配准的同学拿它来对照GPS点位。这里涉及一个细节拾取器返回的默认是CGCS2000经纬度如果你在ArcGIS Pro里输入的也是CGCS2000地理坐标系直接能用但如果你的数据框是WGS84可能微调后更准。在Portal底图配置场景下坐标拾取更多用于预览和验证底图是否正常。我一般会用“天地图坐标拾取”先按几个地标点比如一座桥、一个电视台读取经纬度然后到Portal Web地图里用“定位”功能搜同一个点比对是否重合。如果不重合大概率是坐标系矩阵选错了。写在最后在Portal里接入天地图底图这件事看起来只是填一个URL但实际牵扯到密钥申请、WMTS服务原理、Portal底图配置机制、坐标系选择、网络策略等等多个环节。我个人在实际操作中最深刻的体会是先花5分钟在QGIS里验证服务地址能不能用再花20分钟去配Portal效率最高。磨刀不误砍柴工不要一上来就在Portal的界面里反复试。最后再分享一个小技巧如果底图库添加后Web地图里能出图但图例比如注记图层不显示通常是注记图层没加进来。天地图矢量底图要出完整效果要在底图库里把vec和cva两个图层都加上或者单独再建一条“天地图注记”的底图叠加在矢量底图上。影像底图同理img配cia。这一步不做你看到的就只是一张没有中文注记的“素图”。