灵格网 | Lingerer

从零开始 Mapbox 应用开发
这是本系列开发专栏的第 01 章，我们将会首先从初始化一个脚手架应用程序开始。

应用模板：lingr-dev/lingr-map-mapbox: A Lingerer map application, using Mapbox GL. (github.com)

在当今前端开发领域，构建高效、互动性强的地图应用已经成为许多项目的普遍需求。无论是在数据可视化、WebGIS系统还是创建地图驱动的用户体验中，越来越多的成熟的 地图 SDK 提供强大的功能和灵活的自定义能力，成为了开发者们的首选工具。而通过结合现代化的前端工程中常用的框架和技术，融合前端领域快速开发的优势，可以极大提升开发效率与应用性能。

在本系列文章中，我们将从零开始，逐步探索如何使用 Vite 和 Vue 构建一个完整的 Mapbox 应用开发框架。无论你是刚接触前端地图开发的新手，还是有一定经验的开发者，本系列文章都将尽可能为你提供实用的技巧、经验和建议，也欢迎各位大佬提供更多的应用级思考和见解，让我们一起学习，共同进步。

1. 初始化项目

1）通过Vite CLI脚手架初始化应用

Vite 提供许多开箱即用的脚手架模板，我们可以基于这些模板来初始化我们的应用程序框架。我们可以借助于Vite提供的交互式命令行界面来一步一步创建我们的应用程序框架；这里我们采用 Vue 模板，默认情况下，Vite现在创建基于 Vue 3 的脚手架。

bash

pnpm create vite@latest mymap --template vue
cd mymap
pnpm install

2）安装Mapbox GL JS

Mapbox GL JS是由Mapbox提供的用于浏览器环境中渲染地图的SDK，也是当下主流的地图开发框架之一。

bash

pnpm install

3）启用Scss作为样式文件预处理

现代的前端应用中，由于组件化模式的引入，层次化管理造成样式文件的体积原来越大，原生的CSS语言难以胜任大型应用的样式文件复用、变量化、工具函数化等偏向工程化的需求。为了使用这些现代的CSS语言特性，我们需要为应用引入额外的样式文件预处理工具，这里我们采用 Scss 作为应用的样式文件编写语言。

首先为Vite安装Sass预处理插件

bash

pnpm install sass sass-loader -D

为Vite配置针对Scss的预处理

我们将位于 /src/assets/style/mixin.scss 路径下的文件作为全局公共变量文件注入所有的Scss文件中，这样我们就不必在每个组件的 <style> 标签中重复的引用该文件了。

javascript

export default defineConfig({
  ...
  css: {  
    preprocessorOptions: {    
      scss: {      
        additionalData: '@import "@/assets/style/mixin.scss";',    
      },  
    },
  }
  ...
})

4）配置Vite路径解析别名

目前，绝大多数的应用开发中，约定式的采用 @ 作为 src 文件夹的别名，这的确减少了我们通过相对路径查找需要引入的文件时的负担，也几乎成为绝大多数开发者的习惯，我们也沿用这个约定。

首先，为vite配置路径解析别名，通过 vite.config.js 文件进行配置.

javascript

export default defineConfig({
  ...
  resolve: {  
    alias: {    
      "@": path.resolve(__dirname, "./src"),  
    },
  }
  ...
})

其次，为了让部分IDE能够正确的识别路径别名，并给出智能提示，我们在应用根目录下新建 jsconfig.json 文件。

jsconfig.json

json

{  
  "compilerOptions": {    
    "baseUrl": ".",    
    "paths": {      
      "@/*": ["src/*"]    
    }  
  }
}

2. 配置并创建Mapbox地图

在你的应用中使用 Mapbox 前，需要获取一个 Mapbox 访问令牌。我们需要注册一个可用的 Mapbox账户 并通过控制台获取令牌。

将令牌保存在 .env 文件中，以便于我们在应用中使用它。

text


VITE_MAPBOX_TOKEN=your_mapbox_access_token

创建Map组件

我们在 src/components 目录下创建一个简单的 Map.vue 单文件组件，用来验证Mapbox地图的渲染。

vue


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

<script setup> 
import { ref, onMounted } from 'vue'; 
import mapboxgl from 'mapbox-gl'; 

mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN; 

const mapContainer = ref(null); 

onMounted(() => { 
  const map = new mapboxgl.Map({ 
    container: mapContainer.value, 
    style: 'mapbox://styles/mapbox/streets-v11', 
    center: [0, 0], 
    zoom: 2, 
  }); 
  // 其他地图相关逻辑，如事件监听、图层管理等 
});


<style scoped lang="scss">
.map-container { 
  width: 100%; 
  height: 100vh; 
} 
</style>

在主应用入口中导入Map组件

在 src/App.vue 中导入并使用 Map 组件

vue

<template>
  <Map />
</template>

<script setup>
import Map from './components/Map.vue';
</script>

至此，我们初步完成了一个基于Vite和Vue 3的Mapbox地图应用脚手架的搭建，让我们尝试运行项目，查看地图。

通过执行 pnpm run dev，在浏览器中打开 http://localhost:5173，你应该会看到一个加载了 Mapbox 地图的页面。

接下来，我们将进一步扩展该应用脚手架的功能，为它添加更多企业级的特性。包括但不限于：

引入美观的字体和图标
添加自定义图层和样式
与 Vue 的响应式系统集成以动态管理地图上的数据
使用 Pinia 以全局管理地图状态数据
集成更多其他的工具和API
... ...

如果你觉得本文对你有些许启发，请持续关注我的公众号“戈伊星球”吧！

1. 初始化项目 ​

1）通过Vite CLI脚手架初始化应用 ​

2）安装Mapbox GL JS ​

3）启用Scss作为样式文件预处理 ​

首先为Vite安装Sass预处理插件 ​

为Vite配置针对Scss的预处理 ​

4）配置Vite路径解析别名 ​

2. 配置并创建Mapbox地图 ​

创建Map组件 ​

在主应用入口中导入Map组件 ​

1. 初始化项目

1）通过Vite CLI脚手架初始化应用

2）安装Mapbox GL JS

3）启用Scss作为样式文件预处理

首先为Vite安装Sass预处理插件

为Vite配置针对Scss的预处理

4）配置Vite路径解析别名

2. 配置并创建Mapbox地图

创建Map组件

在主应用入口中导入Map组件