Leaflet加载天地图怎么配?Key在哪里申请?

GIS基础理论
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

要在 Leaflet 里加载天地图,先到天地图云中心控制台注册并完成个人/企业开发者实名认证,创建「浏览器端」应用生成 tk 密钥;再在 L.tileLayer 的瓦片地址中带上 tk,并优先使用球面墨卡托(后缀 _w)服务以匹配 Leaflet 默认 CRS(EPSG:3857)。底图与注记需成对叠加,本地测试白名单可暂空,正式上线必须绑定域名。截至 2026 年 11 月,个人开发者地图 API 日配额通常约 1 万次/服务,超量次日恢复,具体以控制台为准。

Leaflet加载天地图 Key申请和瓦片图层配置流程

天地图 Key 在哪里申请、怎么创建

天地图不自带免密钥公开瓦片。Key(请求参数名一般为 tk)在国家主站体系下申请,省级站点账号与数据不同步。按下面顺序操作即可拿到可用于 Leaflet 的浏览器端密钥。

  1. 打开天地图官网,进入 LBS 开发平台并注册登录(需手机号、邮箱验证)。
  2. 申请成为个人或企业开发者,完成实名认证(个人通常更快)。
  3. 进入云中心控制台 →「我的应用」→ 创建新应用:填写名称、行业类别;应用类型选浏览器端(前端 Leaflet / Web 场景);服务器端适合后端调用并配 IP 白名单。
  4. 配置白名单:本地调试可先留空;正式环境填写域名(支持通配符,如 *.yourdomain.com)。提交后生成 tk。
  5. 在控制台核对权限是否包含地图瓦片类服务,并查看调用统计。个人账号常见上限约 5 个 Key;申请后偶有短延迟才生效。

所有瓦片与 API 请求都必须带 tk=你的密钥,否则易出现 401/403。个人 Key 一般限非商用;商用需按企业协议办理。密钥不要随意公开,正式系统可用后端代理转发或至少锁死域名白名单。

示意:在天地图云中心创建浏览器端应用并获取 tk

Leaflet 怎么配天地图瓦片地址

推荐直接用 L.tileLayer,不要一上来就依赖多年未大更新的第三方封装。Leaflet 稳定版常用 1.9.x;默认 CRS 是 Web 墨卡托,因此瓦片请用 _w(如 vec_w、img_w),与 _c(经纬度)不要混用,否则极易错位。

两种常见地址形态(把密钥换成你的 tk,子域用 t0–t7 负载均衡):

  • WMTS GetTile(官方标准):在 t{s}.tianditu.gov.cn 下请求对应图层的 wmts,带上 SERVICE、REQUEST、VERSION、LAYER、STYLE、TILEMATRIXSET=w、FORMAT、TILEMATRIX={z}、TILEROW={y}、TILECOL={x} 以及 tk。
  • DataServer(插件与不少教程常用):形如 DataServer?T=vec_w&X={x}&Y={y}&L={z}&tk=密钥;T 换成 img_w、cva_w、cia_w 等即可。

最小配置思路:

  1. 引入 Leaflet 的 CSS/JS(CDN 或本地均可),准备一个撑满高度的地图容器。
  2. 用 L.map 创建地图,中心用「纬度在前、经度在后」的数组。
  3. 创建底图 tileLayer:subdomains 设为 0–7,maxZoom 一般到 18,URL 中写入 tk。
  4. 再创建对应注记层并 addTo(注记后加,保证文字在上)。
  5. 用本地 HTTP 服务打开页面,不要直接双击 file:// 打开。
用途 墨卡托(推荐,_w) 经纬度(_c,需自配 CRS)
矢量底图 vec_w vec_c
矢量注记 cva_w cva_c
影像底图 img_w img_c
影像注记 cia_w cia_c
地形晕渲 / 注记 ter_w / cta_w ter_c / cta_c

也可用社区插件(如 Leaflet.ChineseTmsProviders,npm 包约 3.0.6,维护偏旧)写成 chinaProvider 形式并传入自有 key;学习与排错仍建议先掌握原生 tileLayer,看清 URL、子域和图层对。

矢量、影像怎么选,注记为什么必须叠加

矢量底图适合业务系统、行政区与专题叠加;影像底图适合核查、判读与现场展示。同一时刻只开一组底图,避免互相遮挡。天地图的文字标注通常是独立图层:矢量配 cva_*,影像配 cia_*,只加载底图会出现「有路无字」。

  • 验收标准:缩放平移流畅;地名道路名清晰;业务点落在正确城市街区。
  • 图层顺序:先底图后注记;必要时用 pane / zIndex 保证注记在上。
  • 切换底图:可用图层控件把「矢量+注记」「影像+注记」分成两组互斥切换。
  • 坐标系:全项目统一 _w + 3857,或统一自定义经纬度 CRS;禁止 vec_c 与 cva_w 混搭。
示意:矢量/影像底图需分别叠加对应注记层

瓦片空白、403、错位怎么排查

配置失败多半不是 Leaflet「坏了」,而是鉴权、白名单、投影或图层组合问题。按下面顺序查,通常很快定位。

  1. 打开开发者工具 Network:瓦片是否 401/403?先核对 tk 是否完整、应用类型是否为浏览器端、权限是否勾选地图服务。
  2. 白名单:当前访问域名/IP 是否已登记;本地可暂空,上线必填。注意浏览器 referrer 策略过严会导致服务拒绝对外链请求。
  3. 配额:个人日调用触顶后当日无瓦片,次日恢复;可在控制台看统计,勿用爬取式批量下载。
  4. 投影:_c 配默认 3857 会出现漂移;统一改 _w,或为 _c 正确自定义 CRS。
  5. 注记与容器:确认注记已 addTo;检查地图容器高度不为 0;maxZoom 不要超出服务实际级别。
  6. 坐标顺序:Marker 用 [纬度, 经度];GeoJSON 是 [经度, 纬度]。先拿北京、上海等已知点验收。
方式 适用 优点 注意
原生 L.tileLayer 教学、原型、多数业务页 透明、好排错 自行维护 URL 与 Key
项目内封装底图函数 多页面复用 统一 tk、attribution 要约定图层命名
第三方中文底图插件 快速搭演示 写法短 核对维护状态与 Leaflet 版本
后端代理瓦片 隐藏 Key、内网审计 可控限流与缓存 增加服务端成本

常见问题

不申请 Key 能加载天地图吗?

一般不能稳定使用。无 tk、tk 错误、类型或白名单不匹配时,服务会拒绝或返回空瓦片;演示也请用自己申请的浏览器端 Key。

Key 可以写在前端吗?

学习示例可以。正式环境至少绑定域名白名单并限制用途;安全要求高时用后端代理,避免密钥被盗刷配额。

为什么只有底图没有文字?

底图与注记是两套服务。矢量需叠加 cva_w(或同投影的 cva_c),影像需叠加 cia_w;并保证注记图层在底图之上。

vec_w 和 vec_c 怎么选?

Leaflet 默认用 Web 墨卡托时选 _w。只有在你明确自定义了经纬度 CRS、且业务数据同为该体系时,才用 _c;同一项目不要混用。

总结:先在云中心创建浏览器端应用拿到 tk,再用 L.tileLayer 加载成对的 _w 底图与注记,并用 Network 与已知坐标点做验收。建议上线前完成白名单与配额监控;坐标系从一开始就统一,后续叠加 GeoJSON、WMS/WMTS 会省掉大量偏移排查时间。