下面是基于 Vite、Vue 3 和 Mapbox GL 从零搭建一个项目的完整步骤，包括环境搭建、依赖安装、配置和代码示例。

---

1. 初始化项目

首先，使用 Vite 快速创建一个 Vue 3 项目：

npm create vue@latest vue3-mapboxgl --template vue
cd vue3-mapboxgl
npm install

项目目录结构将类似于以下内容：

vue3-mapboxgl/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   ├── router/
│   ├── stores/
│   ├── views/
│   ├── App.vue
│   ├── main.js
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.js

---

2. 安装 mapbox-gl 依赖

安装 Mapbox GL JS 及其类型定义（可选）：

npm install mapbox-gl

---

3. 配置 Mapbox Access Token

Mapbox 需要 Access Token。请前往 Mapbox官网 注册并获取一个 Token。

在 src 目录下创建一个 .env 文件（注意：此文件不要上传到版本控制，添加到 .gitignore）：

VITE_MAPBOX_TOKEN=你的_access_token

---

4. 实现地图组件

创建 src/components/MapView.vue 文件，并编写地图组件代码：

<template>
  <div ref="mapContainer" id="map-container"></div>
</template>

<script lang="ts" setup>
import { onMounted, onBeforeUnmount, ref } from 'vue';
import mapboxgl from "mapbox-gl";
import "mapbox-gl/dist/mapbox-gl.css";

const mapContainer = ref(null);
let map;

onMounted(() => {
  // 设置 Mapbox Access Token 令牌 
  mapboxgl.accessToken = import.meta.env.VITE_APP_MAP_TOKEN;
  console.log(mapboxgl.accessToken);

  // 创建 Map 实例
  console.log(mapContainer.value);
  map = new mapboxgl.Map({
    container: mapContainer.value, // 绑定的 DOM 容器
    style: "mapbox://styles/mapbox/streets-v11", // 地图样式
    center: [120.1551, 30.2741], // 初始中心点经纬度（杭州）
    zoom: 10, // 初始缩放级别
  });

  // 添加缩放和方向控制
  map.addControl(new mapboxgl.NavigationControl());
});

onBeforeUnmount(() => {
  // 销毁地图实例
  if (map) map.remove();
});
</script>

<style>
#map-container {
  width: 100%;
  height: 100vh;
}
</style>

---

5. 在 App.vue 中使用地图组件

修改 src/App.vue 文件：

<template>
 <MapView />
</template>

<script lang="ts" setup>
import MapView from './components/MapView.vue';

</script>

<style>

</style>

---

6. 启动开发服务器

运行以下命令启动项目：

npm run dev

打开浏览器访问 http://localhost:5173，你应该可以看到 Mapbox 地图。

---

7. 添加自定义功能（可选）

1) 添加标记点

在 MapView.vue 的 mounted 方法中加入以下代码：

const marker = new mapboxgl.Marker()
  .setLngLat([120.1551, 30.2741]) // 设置标记点位置
  .addTo(this.map); // 添加到地图

2) 响应用户交互

添加点击事件监听：

this.map.on('click', (e) => {
  const { lng, lat } = e.lngLat;
  alert(`你点击了坐标: ${lng}, ${lat}`);
});

3) 加载自定义图层

示例：加载 GeoJSON 数据：

this.map.on('load', () => {
  this.map.addSource('my-data', {
    type: 'geojson',
    data: {
      type: 'FeatureCollection',
      features: [
        {
          type: 'Feature',
          geometry: { type: 'Point', coordinates: [120.1551, 30.2741] },
          properties: { title: '杭州' },
        },
      ],
    },
  });

  this.map.addLayer({
    id: 'my-data-layer',
    type: 'circle',
    source: 'my-data',
    paint: {
      'circle-radius': 10,
      'circle-color': '#007cbf',
    },
  });
});

---

8. 部署项目

将项目打包后部署到服务器：

npm run build

将生成的 dist 文件夹内容上传到服务器。

---

如果需要更复杂的功能或定制，可以继续扩展组件逻辑，比如结合 Vuex 或 Pinia 管理地图状态，或通过 Mapbox 的 API 添加更多交互。