确认是否使用新版地图API需检查初始化方式是否为new Amap.Map()等新语法、是否启用webgl渲染及强制httpS，若仍用new BMap.Map()报BMap未定义，则CDN未切至GL版。
怎么确认自己用的是“新版”地图 API
所谓“新版”，不是 html5 自带的，而是高德、百度、腾讯等地图服务商在 2023–2025 年陆续推出的 SDK 迭代版本（如高德 v2.0+、百度 BMapGL、腾讯 L7）。它们和旧版最直观的区别是：不兼容 BMap.Map 或 AMap.Map 的老初始化方式，且默认启用 WebGL 渲染、强制 https、要求显式声明 useHTTPS: true 等。如果你的代码里还写着 new BMap.Map(...) 却报 ReferenceError: BMap is not defined，大概率是 CDN 地址没切到 GL 版本。
关键改动查哪？直接看官方迁移公告页
别翻文档首页，去搜「迁移指南」或「v2.x 升级说明」——这是最权威的来源：
- 高德：访问
https://lbs.amap.com/api/jsapi-v2/guide/abc/migration（注意路径含migration） - 百度：搜索「百度地图 JavaScript API GL 版迁移文档」，进官网后找「v3.0 → v3.1+ 升级说明」
- 腾讯：查看
https://lbs.qq.com/webApi/javascriptGL/v1-0/guide/migrate
这些页面会明确列出：废弃方法（如 AMap.Geocoder.search → 改用 AMap.plugin('AMap.Geocoder', ...)）、参数变更（zoom 从整数变为浮点数）、以及必须添加的配置项（如高德 v2.0 要求 key + securityJsCode 双校验）。
html5 Geolocation 和地图 API 是两回事，别混查
很多人搜“HTML5 地图 API”，实际想查的是浏览器原生的定位能力——但它只提供经纬度，不画地图。navigator.geolocation.getCurrentPosition() 没有“新版”，只有浏览器策略收紧：chrome 94+ 起，http:// 页面彻底禁用该 API；ios safari 对后台定位加了 5 分钟超时限制；部分安卓 webview 默认关闭位置权限。这些变化不会出现在地图 SDK 文档里，得查 caniuse.com/geolocation 或 MDN 的 Geolocation.getCurrentPosition 页面更新日志。
立即学习“前端免费学习笔记（深入）”；
本地调试时“API 加载失败”的真实原因
常见现象：控制台报 Failed to load Resource: the server responded with a status of 400 或 Invalid key，但 key 明明是对的。问题往往出在：
- 高德 key 未绑定「Web 平台」白名单域名（localhost 默认允许，但
127.0.0.1不算） - 百度 AK 启用了「SN 加密校验」，但你没配
sn参数，或时间戳偏差 > 60 秒 - 腾讯地图 JSAPI 在本地 file:// 协议下直接被拦截（必须走 http:// 或 https://）
这类错误跟“HTML5 新版”无关，纯属服务商侧的鉴权机制升级，查错要盯紧 Network 面板里请求 URL 的 query 参数和响应 body 的 error message。
真正容易被忽略的，是地图容器 dom 元素必须在调用 new AMap.Map(...) 前已存在且宽高不为 0——新版 SDK 不再容忍“先初始化后挂载”，否则地图空白且无报错。