HTML5嵌入地图本质是调用第三方JS SDK而非原生功能；需引入高德/百度/腾讯SDK，在DOM中创建容器并初始化地图实例，注意坐标系、协议、备案及性能优化等细节。
怎么用 HTML5 嵌入地图：本质是调用 JS SDK，不是 HTML5 原生功能
HTML5 本身不提供地图能力，所谓“HTML5 嵌入地图”，实际是通过 <script></script> 引入第三方地图 JS SDK（如高德、百度、腾讯），再用 JavaScript 创建容器 div 并初始化地图实例。浏览器支持 HTML5 仅意味着能正常运行这些脚本和渲染 Canvas/SVG 底图——别被标题误导，重点在 SDK 调用，不在 HTML 标签。
高德地图 JS API 基础嵌入步骤（含 key 申请和 DOM 容器）
必须先注册高德开放平台账号，创建应用获取 key，否则加载会报错 Invalid Key 或白屏。嵌入流程固定四步：
- 在
中插入 SDK 脚本：<script src="https://webapi.amap.com/maps?v=2.0&key=%E4%BD%A0%E7%9A%84key"></script> - 准备一个带 id 的
div容器，例如：<div id="map" style="width: 100%; height: 400px;"></div>，注意宽高必须可计算（不能是height: auto） - 确保 DOM 加载完成后再初始化，推荐用
AMap.initAMapApiLoader或直接写在底部的<script></script>里 - 创建地图实例：
const map = new AMap.Map('map', {center: [116.397428, 39.90923], zoom: 13});，坐标顺序是[lng, lat]，不是[lat, lng]
百度地图 API 常见报错与绕过限制方法
百度地图对未备案域名、本地 file:// 协议、HTTPS 页面加载 HTTP SDK 有严格校验，典型错误包括：INVALID_REQUEST、Illegal Request、控制台提示 “未授权”。
Java 接口排错助手
下载
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
- 必须使用 HTTPS 加载 SDK：
https://api.map.baidu.com/api?v=3.0&ak=你的ak，HTTP 会直接拒绝 - 本地开发时，不能用双击打开 HTML 文件（file://），需起本地服务（如
python3 -m http.server）或用 VS Code Live Server 插件 - 国内未备案域名会被限流甚至屏蔽，测试阶段建议用 localhost 或已备案子域名
- AK 需绑定 Referer（如
*.example.com），但开发时可临时设为*（上线前务必收紧）
腾讯地图异步加载与 marker 性能陷阱
腾讯地图 SDK 支持异步加载（callback 参数），但容易忽略两个关键点：地图容器必须已存在，且 marker 批量添加时未做聚合会导致卡顿。
立即学习“前端免费学习笔记（深入）”；
- SDK 加载地址示例：
https://map.qq.com/api/js?v=2.exp&callback=initMap&key=OB4BZ-D4W3U-B7VVO-4PJWW-6TKDJ-WPB77，initMap是全局函数名，必须提前声明 - 初始化前检查容器：
if (!document.getElementById('map')) return;，否则报container is not found - 添加超过 50 个
marker时，务必启用MarkerClusterer（需额外引入qq.maps.MarkerClusterer模块），否则页面明显掉帧 - 腾讯地图坐标系默认是 GCJ-02，若数据源是 WGS-84（如 GPS 设备原始坐标），需先调用
qq.maps.convertor.translate转换，否则偏移 300–500 米
真正难的不是加地图，而是处理坐标系混用、跨域限制、移动端 touch 事件冲突、离线 fallback 和 SDK 版本升级断点——这些细节不踩一遍坑很难信。
