# 🗺️ 高德地图SDK加载问题修复指南

## ❌ 问题描述

**错误**: 高德地图SDK未加载，显示占位地图

**原因**: 项目中没有引入高德地图JavaScript SDK，导致 `window.AMap` 不存在

---

## ✅ 解决方案（2种）

### 方案1：引入高德地图SDK（推荐用于生产环境）

#### 步骤1: 申请高德地图API Key

1. 访问 [高德开放平台](https://console.amap.com/)
2. 注册/登录账号
3. 进入"应用管理" → "我的应用"
4. 点击"创建新应用"
5. 创建应用后，添加Key
   - 服务平台：选择 "Web端(JS API)"
   - Key名称：自定义（如：智慧农业地图）
   - 获得 API Key 和 安全密钥

#### 步骤2: 在项目中引入SDK

**方法A: 在 index.html 中引入（推荐）**

找到项目根目录的 `index.html` 或 `public/index.html`，在 `<head>` 标签中添加：

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>智慧农业生产管理系统</title>
  
  <!-- 引入高德地图SDK -->
  <script type="text/javascript">
    window._AMapSecurityConfig = {
      securityJsCode: 'YOUR_SECURITY_JS_CODE', // 替换为你的安全密钥
    }
  </script>
  <script 
    type="text/javascript" 
    src="https://webapi.amap.com/maps?v=2.0&key=YOUR_AMAP_KEY">
  </script>
  <!-- 高德地图SDK引入完成 -->
  
</head>
<body>
  <div id="root"></div>
</body>
</html>
```

**重要**: 
- 将 `YOUR_AMAP_KEY` 替换为你申请的API Key
- 将 `YOUR_SECURITY_JS_CODE` 替换为你的安全密钥

**方法B: 使用动态加载**

如果不想修改 index.html，可以创建一个加载器：

```typescript
// /lib/mapLoader.ts
export const loadAMapScript = (): Promise<void> => {
  return new Promise((resolve, reject) => {
    if (window.AMap) {
      resolve();
      return;
    }

    // 设置安全密钥
    window._AMapSecurityConfig = {
      securityJsCode: 'YOUR_SECURITY_JS_CODE',
    };

    const script = document.createElement('script');
    script.type = 'text/javascript';
    script.src = 'https://webapi.amap.com/maps?v=2.0&key=YOUR_AMAP_KEY';
    script.onload = () => resolve();
    script.onerror = () => reject(new Error('高德地图SDK加载失败'));
    
    document.head.appendChild(script);
  });
};
```

然后在组件中使用：

```typescript
import { loadAMapScript } from '../../../lib/mapLoader';

useEffect(() => {
  loadAMapScript()
    .then(() => {
      initMap();
    })
    .catch((error) => {
      console.error(error);
    });
}, []);
```

#### 步骤3: 验证SDK加载

打开浏览器控制台（F12），输入：

```javascript
console.log(window.AMap);
```

如果输出了对象（不是 undefined），说明SDK加载成功。

---

### 方案2：使用占位地图（适合开发/演示）

如果暂时不需要真实地图，可以继续使用当前的占位地图显示，功能完全正常。

**优点**:
- ✅ 无需申请API Key
- ✅ 无需网络请求
- ✅ 功能演示完整
- ✅ 开发调试方便

**缺点**:
- ❌ 无真实地图背景
- ❌ 无法显示道路、建筑等地理信息

**适用场景**:
- 开发阶段
- 功能演示
- 原型展示

---

## 🔧 完整实施步骤

### 使用方案1（真实地图）

1. **申请Key** (5分钟)
   ```
   访问: https://console.amap.com/
   注册 → 创建应用 → 添加Key → 获取Key和安全密钥
   ```

2. **引入SDK** (2分钟)
   ```html
   <!-- 在 index.html 中添加 -->
   <script>
     window._AMapSecurityConfig = {
       securityJsCode: '你的安全密钥'
     }
   </script>
   <script src="https://webapi.amap.com/maps?v=2.0&key=你的Key"></script>
   ```

3. **重启项目** (1分钟)
   ```bash
   # 停止当前服务
   Ctrl + C
   
   # 重新启动
   npm run dev
   ```

4. **访问页面**
   ```
   智能农机管理系统 → 设备实时监控与定位 → 实时位置追踪
   ```

5. **验证结果**
   - ✅ 看到高德地图背景
   - ✅ 看到农机图标标记
   - ✅ 可以缩放、平移地图
   - ✅ 点击标记查看详情

---

## 📝 示例配置文件

### index.html 完整示例

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>智慧农业生产管理系统</title>
  
  <!-- 高德地图配置 -->
  <script type="text/javascript">
    window._AMapSecurityConfig = {
      securityJsCode: 'abcd1234efgh5678', // 示例安全密钥
    }
  </script>
  
  <!-- 高德地图SDK -->
  <script 
    type="text/javascript" 
    src="https://webapi.amap.com/maps?v=2.0&key=1234567890abcdef">
  </script>
  
  <style>
    body {
      margin: 0;
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
        'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
        sans-serif;
      -webkit-font-smoothing: antialiased;
      -moz-osx-font-smoothing: grayscale;
    }
  </style>
</head>
<body>
  <div id="root"></div>
</body>
</html>
```

---

## 🚀 快速测试

### 测试SDK是否加载成功

打开浏览器控制台，运行：

```javascript
// 测试1: 检查AMap对象
console.log('AMap是否存在:', !!window.AMap);

// 测试2: 检查版本
if (window.AMap) {
  console.log('AMap版本:', window.AMap.version);
}

// 测试3: 创建简单地图
if (window.AMap) {
  const testMap = new window.AMap.Map('test-container', {
    zoom: 10,
    center: [116.397428, 39.90923]
  });
  console.log('地图创建成功:', testMap);
}
```

**预期结果**:
```
AMap是否存在: true
AMap版本: 2.0
地图创建成功: Map { ... }
```

---

## ❓ 常见问题

### Q1: 申请Key后多久生效？
**A**: 立即生效，无需等待。

### Q2: 免费版有限制吗？
**A**: 
- 免费配额: 每天30万次调用
- 对于内部系统完全够用
- 超出配额需要升级付费

### Q3: 安全密钥是否必须？
**A**: 
- 高德地图2.0版本强制要求
- 用于防止Key被盗用
- 必须配置才能正常使用

### Q4: 可以使用其他地图吗？
**A**: 可以，也支持：
- 百度地图 (需要改代码)
- 腾讯地图 (需要改代码)
- OpenStreetMap (开源，无需Key)

### Q5: 本地开发需要Key吗？
**A**: 需要。高德地图SDK无论在哪都需要有效的Key。

---

## 🔐 安全建议

### 保护你的API Key

1. **不要提交到Git**
   ```bash
   # 在 .gitignore 中添加
   .env.local
   ```

2. **使用环境变量**
   ```javascript
   // 在构建工具中配置
   const AMAP_KEY = process.env.REACT_APP_AMAP_KEY;
   ```

3. **限制Key的使用范围**
   - 在控制台设置IP白名单
   - 设置域名白名单
   - 定期更换Key

4. **监控使用量**
   - 在控制台查看调用统计
   - 设置告警阈值
   - 防止异常调用

---

## 📊 方案对比

| 特性 | 方案1: 真实地图 | 方案2: 占位地图 |
|------|----------------|----------------|
| 申请Key | ✅ 需要 | ❌ 不需要 |
| 网络要求 | ✅ 需要 | ❌ 不需要 |
| 地图背景 | ✅ 有 | ❌ 无 |
| 地理信息 | ✅ 完整 | ❌ 无 |
| 缩放平移 | ✅ 支持 | ❌ 不支持 |
| 开发速度 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 演示效果 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| 生产使用 | ✅ 推荐 | ❌ 不推荐 |

---

## 🎯 推荐方案

### 开发阶段
```
使用方案2（占位地图）
- 快速开发，无需配置
- 功能完整，可以调试
- 节省API调用配额
```

### 演示/测试阶段
```
使用方案1（真实地图）
- 申请开发者Key（免费）
- 完整展示地图功能
- 获得真实使用体验
```

### 生产部署
```
使用方案1（真实地图）
- 申请企业Key
- 配置域名白名单
- 设置IP限制
- 监控使用情况
```

---

## 📞 获取帮助

### 高德地图官方资源

1. **开发者文档**: https://lbs.amap.com/api/javascript-api-v2/summary
2. **示例中心**: https://lbs.amap.com/demo/list/js-api-v2
3. **常见问题**: https://lbs.amap.com/faq/js-api-v2
4. **技术论坛**: https://lbs.amap.com/dev/index

### 项目相关文档

- `/REALTIME_LOCATION_TRACKING_COMPLETE.md` - 完整功能说明
- `/REALTIME_MAP_DISPLAY_UPDATE.md` - 地图显示更新

---

## ✅ 检查清单

完成以下步骤后，地图应该正常显示：

- [ ] 已申请高德地图API Key
- [ ] 已获取安全密钥
- [ ] 已在 index.html 中添加SDK引用
- [ ] 已替换 YOUR_AMAP_KEY 为真实Key
- [ ] 已替换 YOUR_SECURITY_JS_CODE 为真实密钥
- [ ] 已重启开发服务器
- [ ] 浏览器控制台显示 `window.AMap` 存在
- [ ] 访问页面能看到地图背景
- [ ] 地图上显示农机标记
- [ ] 可以缩放和平移地图

---

## 🎉 成功标志

当你看到以下内容时，说明配置成功：

1. ✅ 地图区域显示高德地图背景（道路、建筑等）
2. ✅ 农机图标标记正确显示在地图上
3. ✅ 可以使用鼠标滚轮缩放地图
4. ✅ 可以拖拽平移地图
5. ✅ 点击标记能弹出信息窗口
6. ✅ 悬停标记能显示详细信息
7. ✅ 控制台没有错误信息

---

**文档版本**: v1.0  
**创建时间**: 2025-10-17  
**适用范围**: 实时位置追踪功能  
**状态**: ✅ **可立即使用**
