高德地图JS API必须通过HTTPS加载，本地开发需用http.server启动服务，部署必须HTTPS；Key需绑定域名白名单；初始化前须确保AMap就绪，marker坐标须为[lng,lat]数组并指定map实例；移动端需开启touchZoom等交互配置。
高德地图 JS API 必须用 HTTPS 加载
本地直接双击打开 index.html 会白屏或报错 AMap is not defined，因为高德 JS API（https://webapi.amap.com/maps?v=2.0&key=xxx）强制要求页面在 HTTPS 协议下运行，HTTP 或 file:// 协议会被浏览器拦截脚本加载。
实操建议：
- 开发时用
python3 -m http.server 8000启一个本地 HTTP 服务（注意：仅限调试，高德仍会警告，但部分功能可临时跑通） - 真正部署必须走 HTTPS，Nginx/Apache 配好证书，或用 Vercel/Netlify 等自带 HTTPS 的托管平台
- 确保
&key=后面跟的是你在 高德开放平台 申请的 Web 端 Key，且已开启「JavaScript API」服务并绑定域名（localhost和你的线上域名都要加进白名单）
初始化地图前必须等 AMap 全局对象就绪
常见错误是 DOM 加载完就立刻执行 new AMap.Map(...)，但此时高德 SDK 还没下载完成，导致 AMap is not defined 或 AMap.Map is not a constructor。
正确做法是监听 load 事件或用 callback 参数：
立即学习“前端免费学习笔记（深入）”；
<script src="https://webapi.amap.com/maps?v=2.0&key=your_key&callback=initMap"></script>
<script>
function initMap() {
const map = new AMap.Map('map-container', {
center: [116.397428, 39.90923],
zoom: 13
});
}
</script>
不推荐用 window.onload 或 DOMContentLoaded 替代 —— 它们不保证 SDK 已加载完毕。
标记（AMap.Marker）需显式指定 position 坐标数组
很多新手写成 position: {lng: xxx, lat: xxx} 或漏掉 map 参数，结果 marker 不显示、控制台无报错、地图空白。
关键点：
-
position必须是[lng, lat]格式的数组（注意：顺序是经度在前，纬度在后） - 必须传入
map实例，否则 marker 创建了但没挂载到地图上 - 如果坐标来自后端，确认是 GCJ-02 坐标系（高德默认），不是 WGS-84（GPS 原始坐标）—— 否则 marker 会偏移几公里
示例：
const marker = new AMap.Marker({
position: [116.397428, 39.90923],
map: map,
title: '我的位置'
});
移动端触摸体验差？补上 touchZoom 和 dragEnable
HTML5 页面在手机上默认缩放卡顿、拖拽迟滞，甚至完全无法操作，是因为高德地图实例默认对移动端做了保守配置。
初始化地图时务必显式开启交互：
const map = new AMap.Map('map-container', {
center: [116.397428, 39.90923],
zoom: 13,
touchZoom: true,
dragEnable: true,
doubleClickZoom: true,
keyboardEnable: false // 移动端一般关掉键盘缩放
});
另外别忘了在 <head> 加 viewport 声明，否则地图容器可能被缩放挤压：
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
高德地图嵌入本身不难，真正的坑都在环境、时序和坐标系上；Key 白名单没配、HTTP 直接双击、marker 坐标顺序反了、移动端没开 touchZoom —— 这四类问题占了调试时间的 80%。
