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

文章目录

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

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

  
// 1）引入 Loader// 如果编辑器爆 TS 声明缺失，可 `// @ts-ignore` 或安装 @typesimport AMapLoader from \'@amap/amap-jsapi-loader\'import { onMounted, onBeforeUnmount } from \'vue\'// 2）生命周期创建 / 销毁let map: AMap.Map | null = nullonMounted(() => { 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()}).map { width: 100%; height: 100%;}

5.2 在页面中使用

 import Amap from \'@/components/Amap.vue\'

运行 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 扩展实现地图可视化
• 在大屏中用 组件嵌套，动态调整大小、切换图层

祝你开发顺利 🚀