一切福田，不離方寸，從心而覓，感無不通。

从 0 到 1 快速实现海外地图接入（Leaflet + OpenStreetMap）

相关文章：

从 0 到 1 快速实现海外地图接入（Leaflet + OpenStreetMap）

10000+ 点位轻松展示，使用 Leaflet 实现地图海量标记点聚类

解决 Leaflet 高频交互下报错问题，社区、AI、源码三重排查

一. 背景

随着全球化业务发展，我们需要为海外用户提供地图服务。经过技术调研发现：

  1. Google 地图成本问题：Google Maps API 采用按量计费模式，随着用户量增长会产生高昂费用
  2. 国内地图国际化不足：百度、高德等国内地图服务对英文支持有限，海外覆盖不全面，英文展示效果不佳
  3. OpenStreetMap 优势：
    • 完全免费的开源地图数据
    • 全球覆盖且支持多语言
    • 活跃的社区持续更新数据

基于以上考量，我们选择leaflet + OpenStreetMap技术方案：

  • leaflet 提供轻量级、高性能的地图展示能力
  • OpenStreetMap 提供免费可靠的全球地图数据
  • 两者结合既能满足功能需求，又能有效控制成本

二. 介绍

1. Leaflet

leaflet 是一个开源的 JavaScript 库，用于创建交互式、移动友好的网络地图。它轻量级（约 39KB 的 JS 代码），但功能强大，支持大多数桌面和移动平台。

2. OpenStreetMap(OSM)

OpenStreetMap(OSM) 是一个由用户社区创建和维护的免费可编辑的世界地图，常被称为"地理维基百科"。

说到 OpenStreetMap，就不得不说一下地图瓦片。

3. 地图瓦片(Tiles)

地图瓦片是将地图分割成小的正方形图片（通常是 256×256 或 512×512 像素），按不同缩放级别组织起来的系统。这种技术允许：

  1. 高效加载：只加载当前视图需要的部分地图
  2. 快速渲染：预渲染的图片比动态渲染快
  3. 缓存友好：瓦片可以被浏览器和 CDN 缓存
  4. 并行加载：可以同时加载多个瓦片

瓦片坐标系统

瓦片通常使用(x,y,z)坐标标识：

  • z：缩放级别（0 是最小缩放，整个世界显示在一个瓦片中）
  • x 和 y：在该缩放级别下的行列位置

瓦片使用流程

  1. 请求瓦片：当用户查看地图时，Leaflet 根据当前视图的中心和缩放级别计算需要的瓦片坐标
  2. 获取瓦片：从瓦片服务器(如 OpenStreetMap 的服务器)请求这些瓦片
  3. 拼接显示：将获取的瓦片拼接成无缝的地图视图
  4. 预加载：通常还会预加载周边瓦片，以便用户平移地图时流畅显示

4. 二者关系

leaflet 是一个地图显示库，而 OpenStreetMap 是地图数据源之一，也就是瓦片源。Leaflet 可以显示来自 OpenStreetMap 的地图瓦片，也可以显示其他来源的地图数据。OpenStreetMap 数据可以被多种客户端（包括 Leaflet）使用来渲染地图。

除了 OpenStreetMap，Leaflet 的灵活性使其能够兼容多种瓦片源，包括：

  • 商业地图（Google、Bing、HERE）
  • 卫星影像（NASA、Mapbox）
  • 国家专用地图（天地图、Swisstopo）
  • 矢量瓦片（GeoServer、Mapbox）
  • 开源地图（Stamen、Esri）

具体接入方式需参考各服务的 API 文档或对应 leaflet 插件说明，本篇文章不做过多赘述！

接下来，我们将介绍如何借助 Tare 来实现 leaflet + OpenStreetMap 地图，来从 0 到 1 构建一个简单的地图应用程序。

三. 安装

接下来，我借助 Trae IDE 提供的内置智能体 Builder，来帮助我从 0 到 1 开发一个完整的项目。根据我发出的需求， Builder 会调用不同的工具，包括运行命令的工具，来有效地处理我的需求。

在这里，我取消了 Builder 智能体的执行命令，我手动安装必要库 leaflet，最新版本为 1.9.4

1
pnpm install leaflet

还需要添加 types 支持，不然 ts 项目会报类型文件错误

1
pnpm install @types/leaflet

四. 初始化地图

安装完 leaflet 之后，我们就可以，创建一个地图组件。

1. 引入 Leaflet

1
2
import L from 'leaflet'
import 'leaflet/dist/leaflet.css'

2. 添加地图节点

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

3. 初始化 Leaflet

以 London, UK 坐标为中心，设置当前缩放级别为 5

1
const map = L.map('map').setView([51.505, -0.09], 5)

4. 设置瓦片数据源

设置瓦片数据源，并将地图最大支持的放大级别设置为 19

1
2
3
4
5
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution:
    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
  maxZoom: 19
}).addTo(map)

5. 添加一个标记点

1
L.marker([51.5, -0.09]).addTo(map)

6. 给标记点添加弹出框

1
marker.bindPopup('London, UK').openPopup()

完整的代码如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<script lang="ts" setup>
import { onMounted } from 'vue';
 
import L from 'leaflet';
 
import 'leaflet/dist/leaflet.css';
 
onMounted(() => {
  const map = L.map('map').setView([51.505, -0.09], 5);
 
  L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
    attribution:
      '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    maxZoom: 19,
  }).addTo(map);
 
  // 添加标记点位
  L.marker([51.5, -0.09]).addTo(map).bindPopup('London, UK').openPopup();
});
</script>
 
<template>
  <div id="map" style="width: 100%; height: 500px"></div>
</template>

这样，通过以上的代码，一个以London, UK 坐标为中心地图雏形就出来了。

 

将地图放大级别调整为 13，如下图所示，放大可至街道级别：

1
map.setView([51.505, -0.09], 13)

五. 暗黑模式支持

已有项目中支持暗黑模式，所以地图也要支持暗黑模式，问一下 Trae，如何实现暗黑模式？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<script lang="ts" setup>
  import { onMounted, ref } from 'vue'
 
  import L from 'leaflet'
 
  import 'leaflet/dist/leaflet.css'
 
  const darkMode = ref(true)
 
  onMounted(() => {
    const map = L.map('map').setView([51.505, -0.09], 13)
 
    // 浅色图层
    const lightLayer = L.tileLayer(
      'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
      {
        attribution:
          '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
        maxZoom: 19
      }
    )
 
    // 深色图层
    const darkLayer = L.tileLayer(
      'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png',
      {
        attribution:
          '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
        maxZoom: 19
      }
    )
 
    // 根据darkMode适配主题
    darkMode.value ? darkLayer.addTo(map) : lightLayer.addTo(map)
 
    // 添加标记
    L.marker([51.5, -0.09]).addTo(map).bindPopup('London, UK').openPopup()
  })
</script>
 
<template>
  <div id="map" style="width: 100%; height: 100%"></div>
</template>

 

六. 优化报错问题

偶发性报错，因为 leaflet 地图容器被重复初始化导致的。我们需要优化一下流程，确保地图只在组件挂载时初始化一次，并在组件卸载时正确销毁地图实例。

通过添加销毁逻辑和使用 ref 来跟踪地图实例状态来解决这个问题。

最终的代码如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
<script lang="ts" setup>
  import { onMounted, onUnmounted, ref } from 'vue'
 
  import { usePreferences } from '@vben/preferences'
 
  import L from 'leaflet'
 
  import 'leaflet/dist/leaflet.css'
 
  const { isDark } = usePreferences()
  const darkMode = ref(isDark.value)
  const mapInstance = ref<L.Map | null>(null)
 
  onMounted(() => {
    if (mapInstance.value) {
      mapInstance.value.remove()
    }
    mapInstance.value = L.map('map').setView([51.505, -0.09], 5)
 
    // 浅色图层
    const lightLayer = L.tileLayer(
      'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
      {
        attribution:
          '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
        maxZoom: 19
      }
    )
 
    // 深色图层
    const darkLayer = L.tileLayer(
      'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png',
      {
        attribution:
          '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
        maxZoom: 19
      }
    )
 
    darkMode.value
      ? darkLayer.addTo(mapInstance.value as L.Map)
      : lightLayer.addTo(mapInstance.value as L.Map)
 
    // 添加标记
    L.marker([51.5, -0.09])
      .addTo(mapInstance.value as L.Map)
      .bindPopup('London, UK')
      .openPopup()
  })
 
  onUnmounted(() => {
    if (mapInstance.value) {
      mapInstance.value.remove()
      mapInstance.value = null
    }
  })
</script>
 
<template>
  <div id="map" style="width: 100%; height: 100%"></div>
</template>

非常简单，以上代码，简洁版的地图组件就完成了。接下来要实现更多的功能完善，比如：添加标记组、连线、轨迹等功能。

注意：要使用 🪜 才能正确渲染地图哦！

七. 总结

leaflet + OpenStreetMap 是一个强大的组合，它提供了一个简单、灵活且高效的方式来展示全球地图。通过使用 leaflet 提供的地图显示功能，我们可以轻松地将 OpenStreetMap 的地图数据集成到我们的应用程序中。

而 OpenStreetMap 是免费的，同时覆盖了全球的大部分地区，包括大陆、海洋、南极洲等，还支持多种语言、暗黑模式等。

总之，瓦片技术是现代网络地图高效运行的基础，Leaflet 和 OpenStreetMap 的结合提供了一个强大而免费的地图解决方案。

作者：前端梦工厂
链接：https://juejin.cn/post/7497965569879605286
来源：稀土掘金

Copyright © 2026 Longsheng All rights reserved