WebGIS开发入门教程三: 底图怎么加载?天地图Key咋弄?

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

引言：在做 WebGIS开发入门教程三: 底图怎么加载?天地图Key咋弄? 这一步时，很多同学不是卡在地图容器，就是卡在天地图 Key、瓦片地址、坐标系和浏览器跨域提示上。本文按一个最小可运行的 WebGIS 页面来讲：先说明底图加载的基本逻辑，再演示如何申请天地图 Key，并分别给出 Leaflet 和 OpenLayers 的加载示例。

本文适合刚开始学习 WebGIS 的 GIS 学生、前端入门开发者和需要把业务数据叠加到底图上的 GIS 工程师。你不需要先掌握复杂的前端框架，只要知道 HTML、JavaScript 文件怎么打开即可。

背景：为什么 WebGIS 第一步通常是先加载底图

背景：WebGIS 页面通常由三部分组成：地图容器、底图图层、业务图层。底图负责提供地理参照，例如道路、河流、地名、行政区和影像背景；业务图层才是你的点位、管线、地块、监测数据等专题内容。

如果没有底图，用户很难判断业务数据的位置关系。比如同一个点坐标，在没有道路和行政区背景时，只能看到一个孤立的符号；加载天地图矢量底图或影像底图后，才能判断它位于哪条道路、哪个区县、附近有哪些地物。

在国内 WebGIS 入门项目中，天地图是常见选择之一。它提供矢量、影像、地形等瓦片服务，并且通常需要使用天地图 Key，也就是访问令牌。没有正确配置 Key，常见现象包括地图空白、瓦片请求报错、控制台出现权限错误等。

原理：底图加载到底加载了什么

原理：WebGIS 中所谓“加载底图”，本质上是浏览器根据当前地图视图范围和缩放级别，向地图服务请求一张张瓦片图片，然后把这些瓦片拼接成完整地图。

瓦片服务通常包含几个关键参数：

• x：瓦片列号。
• y：瓦片行号。
• z：地图缩放级别。
• tk：天地图 Key，用于鉴权访问。
• 图层类型：例如矢量底图、矢量注记、影像底图、影像注记。

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

• 底图层：提供地图背景，例如矢量道路或卫星影像。
• 注记层：提供地名、道路名、兴趣点名称等文字标注。

所以加载天地图时，通常不是只加一个图层，而是“底图层 + 注记层”一起加。例如矢量底图配矢量注记，影像底图配影像注记。

步骤：申请天地图 Key 并加载底图

步骤：下面按真实开发流程走一遍，从申请 Key 到写出最小可运行页面。

第一步：注册并创建天地图 Key

1. 访问天地图官网，登录或注册账号。
2. 进入开发资源或控制台相关页面。
3. 创建一个新的应用 Key。
4. 根据页面提示填写应用名称、应用类型、服务类型等信息。
5. 保存后复制生成的 Key，也就是后面 URL 中的 tk 参数。

不同时间天地图官网界面可能会调整，但核心逻辑不变：你需要在官方控制台创建应用，然后拿到访问服务用的 Key。不要直接复制别人教程里的 Key，因为它可能已经失效、限流或不允许你的域名使用。

第二步：准备一个最小 HTML 页面

先准备一个普通 HTML 文件，例如 index.html。WebGIS 页面至少需要一个地图容器，并给容器设置宽高。如果容器没有高度，地图即使加载成功也可能看不到。

<div id="map" style="width: 100%; height: 600px;"></div>

在正式项目中，建议把样式写到 CSS 文件里；入门测试时直接写在标签上也可以，方便排查问题。

第三步：用 Leaflet 加载天地图矢量底图

Leaflet 适合轻量 WebGIS 入门，API 简洁。下面示例演示如何加载天地图矢量底图和矢量注记。

<link rel="stylesheet" href="https://unpkg.com/leaflet/dist/leaflet.css">
<script src="https://unpkg.com/leaflet/dist/leaflet.js"></script>

<div id="map" style="width: 100%; height: 600px;"></div>

<script>
  var tiandituKey = "把这里替换成你的天地图Key";

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

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

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

  vecLayer.addTo(map);
  cvaLayer.addTo(map);
</script>

这里的 vec_w 表示天地图 Web 墨卡托矢量底图，cva_w 表示矢量注记。对初学者来说，先用 _w 类型更容易和 Leaflet、OpenLayers 等常见 WebGIS 框架配合。

第四步：用 Leaflet 加载天地图影像底图

如果你需要卫星影像背景，可以把矢量底图换成影像底图，同时加载影像注记。

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

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

imgLayer.addTo(map);
ciaLayer.addTo(map);

img_w 是影像底图，cia_w 是影像注记。注意不要把影像注记叠加到矢量底图上，也不要把矢量注记叠加到影像底图上，虽然技术上可能显示，但视觉效果和语义都不够清晰。

第五步：用 OpenLayers 加载天地图底图

OpenLayers 功能更完整，适合后续扩展坐标转换、矢量编辑、专题渲染和复杂交互。下面是一个 OpenLayers 加载天地图矢量底图的基本写法。

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol/ol.css">
<script src="https://cdn.jsdelivr.net/npm/ol/dist/ol.js"></script>

<div id="map" style="width: 100%; height: 600px;"></div>

<script>
  var tiandituKey = "把这里替换成你的天地图Key";

  var vecLayer = new ol.layer.Tile({
    source: new ol.source.XYZ({
      url: "https://t0.tianditu.gov.cn/DataServer?T=vec_w&x={x}&y={y}&l={z}&tk=" + tiandituKey
    })
  });

  var cvaLayer = new ol.layer.Tile({
    source: new ol.source.XYZ({
      url: "https://t0.tianditu.gov.cn/DataServer?T=cva_w&x={x}&y={y}&l={z}&tk=" + tiandituKey
    })
  });

  var map = new ol.Map({
    target: "map",
    layers: [vecLayer, cvaLayer],
    view: new ol.View({
      center: ol.proj.fromLonLat([116.4074, 39.9042]),
      zoom: 10
    })
  });
</script>

OpenLayers 默认地图视图常用 Web Mercator 投影，设置中心点时可以使用 ol.proj.fromLonLat 把经纬度转换为地图显示坐标。这里是很多入门者容易忽略的点。

常见坑：底图空白、Key 无效、坐标不对怎么排查

常见坑：底图加载失败时，不要只盯着代码看。建议同时检查浏览器控制台、网络请求、地图容器和坐标参数。

坑一：地图容器没有高度

如果 div 没有高度，浏览器页面可能只显示一片空白。先确认地图容器有明确高度，例如 height: 600px 或者父级布局已经正确撑开。

坑二：天地图 Key 没有替换

教程中的 把这里替换成你的天地图Key 必须替换为你自己的 Key。注意不要保留中文、空格或多余引号。最简单的验证方式是打开浏览器开发者工具，查看瓦片请求 URL 中的 tk 是否是你的真实 Key。

坑三：瓦片类型写错

天地图 URL 中的 T=vec_w、T=cva_w、T=img_w、T=cia_w 不能随意改。常见组合如下：

坑四：经纬度顺序写反

Leaflet 的中心点常写为 [纬度, 经度]，例如北京约为 [39.9042, 116.4074]。而很多 GIS 数据和 GeoJSON 坐标习惯写成 [经度, 纬度]。如果顺序写反，地图可能跳到很远的位置。

坑五：坐标系不一致导致业务数据偏移

底图加载成功后，如果点、线、面业务数据明显偏移，问题通常不在天地图 Key，而在坐标系。你需要确认业务数据是 WGS84 经纬度、Web Mercator，还是某个地方坐标系。WebGIS 入门阶段建议先使用标准经纬度数据测试，减少不必要的坐标转换问题。

坑六：本地文件打开方式导致资源异常

有些浏览器安全策略会影响本地文件加载。建议使用一个简单本地服务测试页面，而不是直接双击打开 HTML 文件。例如可以用 Python 启动本地服务：

python -m http.server 8000

然后在浏览器访问 http://localhost:8000。这样更接近真实 WebGIS 项目的运行方式。

方法比较：Leaflet、OpenLayers 和天地图 JS API 怎么选

方法比较：加载天地图底图有多种方式。对于入门学习，不必一开始就追求最复杂的方案，应根据项目目标选择。

如果你只是想完成 WebGIS 开发入门教程中的“底图怎么加载”，建议先用 Leaflet。等你需要图层分组、空间绘制、坐标转换和复杂交互时，再切换或扩展到 OpenLayers。

检查清单：加载天地图底图前后逐项确认

检查清单：当页面没有显示底图，或者显示效果不符合预期时，可以按下面顺序排查。

• 是否已经申请并复制了自己的天地图 Key。
• URL 中是否正确拼接了 tk=你的Key。
• 地图容器是否有明确宽度和高度。
• 是否同时加载了底图层和注记层。
• 矢量底图是否搭配 vec_w 和 cva_w。
• 影像底图是否搭配 img_w 和 cia_w。
• 浏览器控制台是否有 403、404、Key 无效或网络错误。
• 经纬度顺序是否写对。
• 业务数据坐标系是否与 WebGIS 地图视图匹配。
• 是否通过本地服务或正式 Web 服务访问页面，而不是只依赖双击打开文件。

经验建议：底图空白时，先打开浏览器开发者工具的 Network 面板，看瓦片请求是否成功。只看页面效果，很容易把 Key、URL、容器高度和坐标问题混在一起。

FAQ：天地图 Key 和 WebGIS 底图加载常见问题

Q1：天地图 Key 可以不申请吗？

不建议。实际开发应使用自己申请的天地图 Key。没有 Key 或使用无效 Key，可能导致瓦片请求失败、访问受限或后续上线不可控。

Q2：为什么我加载了天地图底图，但是没有地名？

通常是只加载了底图层，没有加载注记层。矢量底图需要搭配 cva_w，影像底图需要搭配 cia_w。底图负责背景，注记负责文字标注。

Q3：Leaflet 中北京中心点应该写成什么？

Leaflet 常用 [纬度, 经度] 的写法。北京可以写成 [39.9042, 116.4074]。如果写成 [116.4074, 39.9042]，位置就会明显错误。

Q4：为什么底图出来了，但我自己的 GeoJSON 点位偏移？

这通常是坐标系问题。GeoJSON 常用经纬度坐标，但你的数据可能来自投影坐标、地方坐标或经过加密偏移的坐标。先确认数据源坐标系，再决定是否需要转换。

Q5：天地图矢量底图和影像底图可以同时加载吗？

技术上可以叠加，但一般不建议把两个完整底图同时显示。更常见的做法是提供图层切换控件，让用户在矢量底图和影像底图之间切换。

Q6：WebGIS 入门应该先学 Leaflet 还是 OpenLayers？

如果目标是快速理解底图、标记点、弹窗和简单交互，先学 Leaflet 更顺手。如果目标是企业级 WebGIS、复杂图层控制、绘制编辑和更多坐标处理，OpenLayers 更适合长期深入。

结论：先把底图稳定加载出来，再谈业务图层

结论：WebGIS 入门不要一开始就堆复杂功能。对于“底图怎么加载、天地图 Key 咋弄”这个问题，核心就是三件事：申请自己的天地图 Key，正确拼接瓦片服务地址，在 Leaflet 或 OpenLayers 中把底图层和注记层添加到地图。

当底图稳定显示后，再叠加 GeoJSON、接口数据、业务点位和专题样式，调试效率会高很多。后续如果出现点位偏移、图层不显示或性能变慢，也可以基于这套底图加载流程逐步排查。