GIS基础理论 API Key GIS开发

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

2025-12-02 GIS基础理论

wowwwai GIS研习社 · 工具流程与项目排障

Leaflet加载天地图怎么配?Key在哪里申请? 这是很多 WebGIS 初学者在做底图加载时遇到的第一个问题：Leaflet 本身只负责地图容器、图层控制和交互，天地图底图需要通过天地图开放平台提供的服务地址和 Key 才能正常访问。本文按实际项目流程讲清楚 Key 申请、服务地址配置、经纬度坐标系注意事项，以及常见报错排查。

引言：Leaflet加载天地图的基本思路

在 Leaflet 中加载天地图，本质上是把天地图的瓦片服务作为 L.tileLayer 添加到地图中。你需要准备三样东西：

一个 Leaflet 页面环境，包括 leaflet.css 和 leaflet.js。
天地图开放平台申请的 Key，也常写作 tk。
正确的天地图瓦片服务 URL，例如矢量底图、影像底图、注记图层等。

如果只是学习和测试，建议先用天地图的经纬度瓦片服务，也就是 URL 中常见的 tilematrixset=c。它与 Leaflet 默认的经纬度显示方式更容易理解，适合入门排错。

Leaflet加载天地图 Key申请和瓦片图层配置流程 — Leaflet 加载天地图的典型流程：先申请 Key，再把天地图瓦片服务 URL 配置到 Leaflet 图层中。

背景：为什么 Leaflet 不能直接“打开天地图”

Leaflet 是一个前端地图库，它不自带天地图数据。它能显示什么地图，取决于你给它添加了什么图层服务。天地图提供的是在线瓦片服务，Leaflet 通过 HTTP 请求一张张瓦片图片，然后拼接成连续地图。

很多人配置失败，通常不是 Leaflet 本身的问题，而是下面几类原因：

没有申请天地图 Key，或者 Key 没有正确放到 URL 的 tk 参数中。
瓦片地址写错，例如图层类型、坐标系类型、URL 参数拼写错误。
把经纬度服务和 Web 墨卡托服务混用，导致底图和业务数据位置不一致。
浏览器控制台出现 403、404、跨域、网络访问失败等错误，但没有检查。
只加载了底图，没有加载注记图层，所以看不到地名、道路名等文字。

原理：天地图 Key、瓦片地址和 Leaflet 图层的关系

天地图 Key 是天地图开放平台用于识别调用者身份的访问凭证。配置 Leaflet 加载天地图时，Key 一般作为 tk 参数追加到瓦片服务 URL 后面。

一个常见的天地图瓦片 URL 结构如下：

https://t{s}.tianditu.gov.cn/DataServer?T=vec_c&x={x}&y={y}&l={z}&tk=你的Key

这里几个参数需要理解：

T：图层类型，例如 vec_c 表示矢量底图经纬度服务，cva_c 表示矢量注记经纬度服务。
x、y、z：瓦片列号、行号和缩放级别，由 Leaflet 自动替换。
s：子域名编号，用于分散请求，例如 0 到 7。
tk：你的天地图 Key。

天地图常见图层类型可以简单理解为：

用途	经纬度服务示例	说明
矢量底图	`vec_c`	道路、水系、行政区等基础地图内容
矢量注记	`cva_c`	地名、道路名、兴趣点文字标注
影像底图	`img_c`	遥感影像或卫星影像底图
影像注记	`cia_c`	叠加在影像上的文字标注
地形晕渲	`ter_c`	地形表现相关底图
地形注记	`cta_c`	地形图文字标注

注意：天地图服务地址和平台规则可能会调整，正式项目上线前应以天地图开放平台官方文档为准。本文重点讲 Leaflet 配置方法和排错思路。

步骤：天地图 Key 在哪里申请

第一步：进入天地图开放平台

打开天地图开放平台官方网站，注册并登录账号。一般需要完成手机号、邮箱或单位信息等基础认证，具体要求以平台当前页面为准。

第二步：创建应用

登录后进入控制台或应用管理页面，创建一个新应用。应用名称可以写成项目名，例如 leaflet-demo、webgis-test 或单位内部系统名称。

创建应用时，通常会涉及应用类型、服务范围、域名限制等配置。学习阶段可以先按平台允许的测试配置创建；生产环境建议绑定正式域名，避免 Key 被他人滥用。

第三步：获取 Key

应用创建成功后，平台会生成一个访问 Key。这个 Key 就是 Leaflet 加载天地图时 URL 中 tk= 后面的值。

例如你的 Key 是：

1234567890abcdef1234567890abcdef

那么瓦片地址应写成：

https://t{s}.tianditu.gov.cn/DataServer?T=vec_c&x={x}&y={y}&l={z}&tk=1234567890abcdef1234567890abcdef

第四步：确认 Key 权限和限制

如果你已经配置了 Key 但仍然无法加载，重点检查：

Key 是否复制完整，前后是否多了空格。
是否配置了域名白名单，而当前访问地址不在白名单中。
是否超过平台调用配额或访问限制。
是否创建了错误类型的应用，导致服务权限不匹配。
是否在本地文件方式 file:// 打开页面，建议改用本地 HTTP 服务访问。

步骤：Leaflet加载天地图矢量底图和注记

下面给出一个最小可运行示例。你只需要把 你的天地图Key 替换成自己的 Key，然后通过本地 HTTP 服务打开页面即可。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Leaflet加载天地图示例</title>
  <link rel="stylesheet" href="https://unpkg.com/leaflet/dist/leaflet.css">
  <style>
    html, body, #map {
      width: 100%;
      height: 100%;
      margin: 0;
    }
  </style>
</head>
<body>
  <div id="map"></div>

  <script src="https://unpkg.com/leaflet/dist/leaflet.js"></script>
  <script>
    const tk = '你的天地图Key';

    const map = L.map('map', {
      center: [39.9042, 116.4074],
      zoom: 10
    });

    const vec = L.tileLayer(
      'https://t{s}.tianditu.gov.cn/DataServer?T=vec_c&x={x}&y={y}&l={z}&tk=' + tk,
      {
        subdomains: ['0', '1', '2', '3', '4', '5', '6', '7'],
        maxZoom: 18,
        attribution: '地图数据 © 天地图'
      }
    );

    const cva = L.tileLayer(
      'https://t{s}.tianditu.gov.cn/DataServer?T=cva_c&x={x}&y={y}&l={z}&tk=' + tk,
      {
        subdomains: ['0', '1', '2', '3', '4', '5', '6', '7'],
        maxZoom: 18
      }
    );

    vec.addTo(map);
    cva.addTo(map);
  </script>
</body>
</html>

这个示例中，vec_c 是矢量底图，cva_c 是矢量注记。实际项目中通常两者都要加载，否则地图上可能只有道路和色块，看不到地名文字。

步骤：Leaflet加载天地图影像底图

如果你需要在 Leaflet 中加载天地图影像底图，可以把 vec_c 和 cva_c 替换为影像图层和影像注记图层。

const img = L.tileLayer(
  'https://t{s}.tianditu.gov.cn/DataServer?T=img_c&x={x}&y={y}&l={z}&tk=' + tk,
  {
    subdomains: ['0', '1', '2', '3', '4', '5', '6', '7'],
    maxZoom: 18,
    attribution: '地图数据 © 天地图'
  }
);

const cia = L.tileLayer(
  'https://t{s}.tianditu.gov.cn/DataServer?T=cia_c&x={x}&y={y}&l={z}&tk=' + tk,
  {
    subdomains: ['0', '1', '2', '3', '4', '5', '6', '7'],
    maxZoom: 18
  }
);

img.addTo(map);
cia.addTo(map);

影像底图适合地块核查、遥感判读、现场踏勘展示等场景。矢量底图适合业务系统、专题图叠加和行政区展示。不要把所有底图同时打开，否则会互相遮挡。

常见坑：Leaflet加载天地图不显示怎么排查

1. Key 写错或没有替换

最常见的问题是代码里仍然保留 你的天地图Key，或者复制 Key 时少了一位。打开浏览器开发者工具，查看 Network 面板，如果瓦片请求返回 403 或认证相关错误，优先检查 Key。

2. 把 HTML 直接双击打开

很多前端库和在线服务在 file:// 环境下会出现异常。建议使用本地 HTTP 服务，例如在项目目录执行：

python -m http.server 8000

然后访问：

http://localhost:8000

3. 只加载底图，没有加载注记

天地图底图和注记通常是分开的。矢量底图 vec_c 不等于完整带文字地图，地名道路名需要叠加 cva_c。影像底图也是一样，常配合 cia_c 使用。

4. 经纬度服务和墨卡托服务混用

天地图服务中，后缀 _c 通常表示经纬度服务，后缀 _w 通常表示 Web 墨卡托服务。Leaflet 默认 CRS 是 EPSG:3857，但很多入门示例会使用经纬度天地图服务配合特定配置或插件。实际项目中，如果你的业务数据、底图、坐标转换没有统一，就可能出现偏移、错位或比例异常。

如果你只是做国内 WebGIS 入门演示，建议先保持所有天地图图层使用同一套服务类型，不要一个图层用 vec_c，另一个图层用 cva_w。

5. 业务数据坐标系没有确认

Leaflet 接收点坐标时常用格式是 [纬度, 经度]，而 GeoJSON 坐标顺序是 [经度, 纬度]。这两个顺序经常被混淆。

// Leaflet Marker：纬度在前，经度在后
L.marker([39.9042, 116.4074]).addTo(map);

// GeoJSON：经度在前，纬度在后
{
  "type": "Point",
  "coordinates": [116.4074, 39.9042]
}

方法比较：Leaflet加载天地图的几种配置方式

方式	适用场景	优点	注意事项
直接使用 `L.tileLayer`	简单项目、教学演示、原型验证	代码少，容易排错	需要自己管理图层地址、Key 和坐标系
封装为自定义底图函数	多个页面复用同一套底图	便于统一维护 Key、URL 和 attribution	需要规范项目结构
使用第三方天地图 Leaflet 插件	需要处理复杂坐标系或成熟封装	可能减少底层配置工作	要确认插件维护状态和兼容的 Leaflet 版本
通过后端代理访问瓦片	内网系统、权限控制、隐藏 Key	便于审计、限流和保护 Key	增加服务器压力和缓存设计成本

对 GIS 学习者来说，建议先掌握 L.tileLayer 的直接配置方式。这样你能看懂天地图 URL、瓦片坐标和图层叠加关系，后续再使用插件或封装会更稳。

检查清单：上线前确认这些配置

天地图 Key 已在开放平台创建，并且复制完整。
页面中的 tk 参数已经替换为真实 Key。
底图和注记使用同一类服务，例如都使用 _c 或都使用同一套项目要求的服务。
浏览器 Network 面板中瓦片请求返回正常状态码。
矢量底图已叠加矢量注记，影像底图已叠加影像注记。
业务点、线、面数据的坐标系和坐标顺序已经确认。
正式环境已配置域名白名单或应用限制，避免 Key 泄露后被滥用。
地图页面已保留必要的数据来源 attribution。
移动端访问时地图容器高度不是 0。
如果通过内网或政务网络访问，已确认网络能访问天地图服务域名。

FAQ：Leaflet加载天地图常见问题

Leaflet加载天地图必须申请 Key 吗？

通常需要。天地图开放服务一般通过 Key 进行访问控制和调用统计。没有 Key、Key 错误或 Key 权限不匹配，都可能导致瓦片无法正常加载。

天地图 Key 可以写在前端代码里吗？

学习示例可以直接写在前端，便于理解。正式项目不建议完全裸露 Key，至少应配置域名限制、调用限制；对安全要求较高的系统，可以考虑后端代理和访问控制。

为什么 Leaflet 加载天地图只有底图没有文字？

因为天地图底图和注记通常是两个图层。矢量底图需要叠加 cva_c 注记，影像底图需要叠加 cia_c 注记。只加载底图时，文字标注可能不会显示。

Leaflet加载天地图时 vec_c 和 vec_w 有什么区别？

可以简单理解为坐标系和瓦片体系不同。_c 常用于经纬度服务，_w 常用于 Web 墨卡托服务。项目中不要随意混用，尤其是还要叠加 GeoJSON、WMS、WMTS 或业务空间数据时，更要统一坐标系。

为什么我的点位叠加到天地图上偏了？

常见原因包括坐标系不一致、经纬度顺序写反、数据本身经过了错误转换，或者底图服务类型和业务数据 CRS 没有统一。先用一个已知坐标点测试，例如北京、上海等明显位置，再检查数据坐标顺序。

Leaflet加载天地图可以切换矢量和影像吗？

可以。可以使用 L.control.layers 管理底图组，把矢量底图加矢量注记作为一组，把影像底图加影像注记作为另一组。实际项目中也可以通过按钮控制图层显示和隐藏。

结论：先申请 Key，再统一图层和坐标系

Leaflet加载天地图并不复杂，核心就是申请天地图 Key，把 Key 放入 tk 参数，然后用 L.tileLayer 加载正确的瓦片服务地址。真正容易出错的是 Key 权限、注记图层遗漏、坐标系混用和经纬度顺序写反。

建议 GIS 初学者按“申请 Key、加载矢量底图、叠加注记、检查 Network、再叠加业务数据”的顺序操作。这样不仅能把天地图显示出来，也能为后续 WebGIS 项目中的底图切换、专题图叠加和空间数据发布打好基础。