在 Vue 3 项目中集成高德地图（附 Key 与安全密钥申请全流程）

本文基于 Vue 3 脚手架演示，演示如何申请高德 Web JS API Key / 安全密钥并在项目中加载 2.0 版本的 JS SDK。
高德后台 UI 若有微调，请以官方页面为准。

1 | 为什么选用高德地图

• 免费额度充足：个人 / 企业每天各 300 000 次 JS API 调用。
• 生态完整：道路/逆地理/路径规划/天气/热力图…插件丰富。
• 2.0 SDK 新特性：官方 TypeScript 声明、3D 视图、WebGL 加速。

2 | 申请 Web JS API Key & 安全密钥

2.1 注册并登陆

1. 访问 https://lbs.amap.com/
2. 使用手机号 / 邮箱注册开发者账号，完成实名认证（个人可身份证 / 企业可执照）。

2.2 创建应用

1. 登录后进入【控制台 → 我的应用】
2. 点击【创建新应用】，填写：
   • 应用名称：随意，如 “vue3-dashboard”
   • 应用类型：选择 Web 服务
3. 创建后自动分配一个 Key（如 4a2…c89dc）。

2.3 配置 JS API 安全设置（必做）

2022 年后，高德将 JS Key 强制绑定域名白名单，并推荐启用二次校验 “安全密钥”。

1. 在应用详情页，切换到【JS API】标签
2. 添加域名
   • 生产环境：example.com 或 map.example.com
   • 本地调试：localhost / 127.0.0.1 建议也勾选
   • 不用写协议（http/https）
3. 开启安全密钥（勾选即可生成一串 32 位字符串，如 8fb2…9f31）
4. 点击保存，等待 1-2 分钟生效。

3 | 初始化 Vue 3 项目

# 1. 创建项目
npm create vue@latest  my-map-app
# 2. 进入目录
cd my-map-app
# 3. 选项勾选：TypeScript / Router / Pinia 按需
# 4. 安装依赖
npm i

Vite 默认将项目跑在 http://localhost:5173，记得把该端口域名加入白名单。

4 | 安装并配置 @amap/amap-jsapi-loader

npm i @amap/amap-jsapi-loader --save

该包由高德官方维护，用于懒加载 JS SDK，自动去掉多余脚本标签，亦可配合 vite-plugin-amap 等插件做 CDN 加速。

5 | 编写 Map 组件 – 最小示例

5.1 src/components/Amap.vue

<template>
  <!-- 地图容器必须指定宽高 -->
  <div id="amap-container" class="map"></div>
</template>

<script setup lang="ts">
// 1）引入 Loader
// 如果编辑器爆 TS 声明缺失，可 `// @ts-ignore` 或安装 @types
import AMapLoader from '@amap/amap-jsapi-loader'
import { onMounted, onBeforeUnmount } from 'vue'

// 2）生命周期创建 / 销毁
let map: AMap.Map | null = null

onMounted(() => {
  AMapLoader.load({
    key: 'AAAAAAAAAAAAAAAAAAAAA',     // 你的 Web JS Key
    securityJsCode: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAA', // 开启安全密钥后必须写(你的密钥)
    version: '2.0',
    plugins: ['AMap.Scale', 'AMap.ToolBar']
  })
    .then((AMap) => {
      map = new AMap.Map('amap-container', {
        viewMode: '3D',
        center: [113.625368, 34.746599], // 初始化中心点（郑州）
        zoom: 11
      })
      // 添加控件
      map.addControl(new AMap.Scale())
      map.addControl(new AMap.ToolBar())
    })
    .catch((e) => {
      console.error('高德地图加载失败', e)
    })
})

onBeforeUnmount(() => {
  map?.destroy()
})
</script>

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

5.2 在页面中使用

<template>
  <Amap style="width: 100%; height: 600px" />
</template>

<script setup lang="ts">
import Amap from '@/components/Amap.vue'
</script>

运行 npm run dev，即可看到地图。

6 | 常见问题 & 调试技巧

7 | 结语

本文演示了完整的高德 Key / 安全密钥申请流程，并给出 **Vue 3 ** 项目中最小可运行的地图示例。
接下来你可以：

• 使用 AMap.Marker / AMap.InfoWindow 绘制自定义点
• 结合 ECharts 扩展实现地图可视化
• 在大屏中用 <Amap /> 组件嵌套，动态调整大小、切换图层

祝你开发顺利 🚀