atchain-mapbox-vue/VITE_SETUP.md

A Vue 3 MapBox component library with subway lines, stations, markers and polygons support. Zero dependencies except Vue 3 and Mapbox GL JS.

# 🔧 Vite 项目配置指南

如果你在使用 `atchain-mapbox-vue` 时遇到 mapbox-gl 导入问题，请按照以下步骤配置你的 Vite 项目。

## 🚨 常见错误

```
Uncaught SyntaxError: The requested module '/node_modules/mapbox-gl/dist/mapbox-gl.js' does not provide an export named 'default'
```

## ✅ 解决方案

### 1. 更新 vite.config.ts

在你的 `vite.config.ts` 中添加以下配置：

```typescript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  optimizeDeps: {
    include: ['mapbox-gl']
  },
  define: {
    global: 'globalThis'
  }
})
```

### 2. 导入 CSS 样式

在你的 `main.ts` 中添加 mapbox-gl CSS：

```typescript
import { createApp } from 'vue'
import App from './App.vue'
import 'mapbox-gl/dist/mapbox-gl.css'  // 添加这行

createApp(App).mount('#app')
```

### 3. 安装依赖

确保安装了正确的依赖：

```bash
npm install atchain-mapbox-vue mapbox-gl
```

### 4. 使用组件

```vue
<template>
  <div class="w-full h-screen">
    <MapBox 
      token="your-mapbox-token"
      :center="[121.431502, 31.214212]"
      :zoom="14"
    >
      <MapBoxMarker 
        src="/images/marker.png"
        id="marker-1"
        width="50px"
        height="50px"
      />
    </MapBox>
  </div>
</template>

<script setup lang="ts">
import { MapBox, MapBoxMarker } from 'atchain-mapbox-vue'
</script>
```

## 🔍 故障排除

### 问题 1: 模块导入错误
**解决**: 确保 `vite.config.ts` 中包含 `optimizeDeps.include: ['mapbox-gl']`

### 问题 2: 样式缺失
**解决**: 在 `main.ts` 中导入 `mapbox-gl/dist/mapbox-gl.css`

### 问题 3: 全局变量错误
**解决**: 在 `vite.config.ts` 中添加 `define: { global: 'globalThis' }`

### 问题 4: TypeScript 类型错误
**解决**: 确保安装了 `@types/geojson`：
```bash
npm install -D @types/geojson
```

## 📦 完整的 package.json 示例

```json
{
  "dependencies": {
    "vue": "^3.0.0",
    "atchain-mapbox-vue": "^1.0.1",
    "mapbox-gl": "^2.0.0"
  },
  "devDependencies": {
    "@types/geojson": "^7946.0.0",
    "@vitejs/plugin-vue": "^4.0.0",
    "vite": "^4.0.0"
  }
}
```

## 🎯 验证配置

配置完成后，重启开发服务器：

```bash
npm run dev
```

如果配置正确，你应该能看到地图正常加载，没有控制台错误。

## 📞 需要帮助？

如果仍有问题，请：
1. 检查 mapbox-gl 版本兼容性
2. 清除 node_modules 重新安装
3. 查看浏览器控制台的详细错误信息
4. 提交 Issue 到 GitHub 仓库