下面是基于 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 添加更多交互。