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

文章目录

- [1 | 为什么选用高德地图](#1 | 为什么选用高德地图)
- [2 | 申请 Web JS API Key & 安全密钥](#2 | 申请 Web JS API Key & 安全密钥)
- - [2.1 注册并登陆](#2.1 注册并登陆)
  - [2.2 创建应用](#2.2 创建应用)
  - [2.3 配置 JS API 安全设置（必做）](#2.3 配置 JS API 安全设置（必做）)
- [3 | 初始化 Vue 3 项目](#3 | 初始化 Vue 3 项目)
- [4 | 安装并配置 `@amap/amap-jsapi-loader`](#4 | 安装并配置 @amap/amap-jsapi-loader)
- [5 | 编写 Map 组件 -- 最小示例](#5 | 编写 Map 组件 – 最小示例)
- - [5.1 `src/components/Amap.vue`](#5.1 src/components/Amap.vue)
  - [5.2 在页面中使用](#5.2 在页面中使用)
- [6 | 常见问题 & 调试技巧](#6 | 常见问题 & 调试技巧)
- [7 | 结语](#7 | 结语)

本文基于 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 注册并登陆

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

2.2 创建应用

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

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

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

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

3 | 初始化 Vue 3 项目

bash 复制代码

# 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`

bash 复制代码

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

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

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

5.1 `src/components/Amap.vue`

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 在页面中使用

vue 复制代码

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

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

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

6 | 常见问题 & 调试技巧

现象	解决方案
控制台报 `INVALID_USER_DAILY`	免费额度耗尽，等待次日或付费。
报 `Referer not allowed`	白名单未配置或未生效，检查域名拼写；保存后等 1-2 分钟。
地图无法拖动、缩放卡顿	未设置容器宽高 / 父元素 `display:none` 时初始化；调整 `width/height`。
TypeScript `Cannot find module '@amap/...`	官方暂未发布完整 d.ts，可 `// @ts-ignore` 或自行安装 `@types/amap-js-api`（第三方）。

7 | 结语

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

接下来你可以：

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

祝你开发顺利 🚀