安装

本指南详细介绍 MapboxGL 的安装和配置方法。

环境要求

• Node.js 16.0 或更高版本
• 现代浏览器（Chrome、Firefox、Safari、Edge）

安装方式

方式一：使用包管理器

npm

npm install mapbox-gl

yarn

yarn add mapbox-gl

pnpm

pnpm add mapbox-gl

方式二：使用 CDN

<!-- Mapbox GL JS -->
<script src="https://cdn.jsdelivr.net/npm/mapbox-gl@3.7.0/dist/mapbox-gl.min.js"></script>

<!-- Mapbox GL CSS -->
<link href="https://cdn.jsdelivr.net/npm/mapbox-gl@3.7.0/dist/mapbox-gl.min.css" rel="stylesheet">

在项目中使用

Vite 项目

// main.js 或 main.ts
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

// 设置访问令牌
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN

export { mapboxgl }

// .env
VITE_MAPBOX_TOKEN=your_access_token_here

Vue 3 项目

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

<script setup>
import { ref, onMounted } from 'vue'
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

const mapContainer = ref(null)

onMounted(() => {
  const map = new mapboxgl.Map({
    container: mapContainer.value,
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [116.3974, 39.9093],
    zoom: 11
  })
})
</script>

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

React 项目

import { useEffect, useRef } from 'react'
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN'

function Map() {
  const mapContainer = useRef(null)
  const map = useRef(null)

  useEffect(() => {
    if (map.current) return

    map.current = new mapboxgl.Map({
      container: mapContainer.current,
      style: 'mapbox://styles/mapbox/streets-v12',
      center: [116.3974, 39.9093],
      zoom: 11
    })

    return () => {
      map.current.remove()
    }
  }, [])

  return <div ref={mapContainer} style={{ width: '100%', height: '100vh' }} />
}

export default Map

开发工具

TypeScript 类型定义

npm install @types/mapbox-gl --save-dev

Vue 开发工具

如果你使用 Vue，推荐安装官方的 MapboxGL Vue 组件：

npm install @studiometa/vue-mapbox-gl
# 或
npm install v-mapbox

性能优化建议

性能优化

1. 使用最新版本的 MapboxGL
2. 合理设置 preserveDrawingBuffer 选项
3. 对于大量数据，考虑使用数据聚类
4. 使用 WebGL 2.0 以获得更好的性能

故障排除

问题：地图不显示

解决方案：

1. 检查访问令牌是否有效
2. 确认容器元素有明确的高度和宽度
3. 检查浏览器控制台是否有错误信息

问题：样式加载失败

解决方案：

1. 确保正确引入 CSS 文件
2. 检查样式 URL 是否正确
3. 验证网络连接

问题：TypeScript 类型错误

解决方案：

npm install @types/mapbox-gl --save-dev

或在 tsconfig.json 中添加：

{
  "compilerOptions": {
    "types": ["mapbox-gl"]
  }
}