最常卡在地图容器不渲染和Autocomplete下拉被遮挡：需确保容器有宽高且已挂载（如监听shown.bs.modal），并设.amap-sug-result{z-index:1060!important}；同时必须配置_AMapSecurityConfig.securityJsCode与AK匹配且域名一致。
在 Bootstrap 项目中集成高德地图 API，最常卡住的地方不是“怎么引入”，而是「地图容器不渲染」或「Autocomplete 下拉框被遮挡」——尤其在 Modal、Dialog 等弹层组件里。核心问题就两个：DOM 渲染时机不对 + z-index 层级冲突。
地图容器必须有明确宽高且非 display: none
Bootstrap 的 modal、collapse 或 Vue/React 的懒加载 Dialog 默认用 display: none 或条件渲染控制显隐，而高德地图 AMap.Map 初始化时会读取容器的 offsetWidth 和 offsetHeight。若为 0，地图就白屏或报错 Invalid size。
- 确保地图容器（如
div#container）在初始化前已挂载且可见，比如在shown.bs.modal事件后调用new AMap.Map(...) - 不要把
id="container"放在v-if或ngIf内部；Vue 用户建议改用v-show，React 用户可用useState控制 visibility 而非 mount/unmount - 给容器加内联样式
style="width:100%; height:400px;"，避免依赖 CSS 类（某些 Bootstrap 类如.d-none会干扰）
Autocomplete 下拉列表被 Modal 遮盖
高德 Autocomplete 的下拉面板默认 z-index: 100，而 Bootstrap 5 的 modal-backdrop 是 z-index: 1050，modal-content 是 z-index: 1055，所以搜索建议框直接被盖住，看起来像“失效”。
Map RTOS SDK - 高德地图嵌入式 Map SDK 接入助手，支持栅格/矢量 Map 地图渲染、覆盖物绘制、轨迹导航及适配器实现指南
- 在全局 CSS 中强制提升层级：
.amap-sug-result { z-index: 1060 !important; } - 如果使用 Vue CLI 或 Webpack，需确保该样式未被 scoped 影响；可放在
<style></style>标签外，或用:deep(.amap-sug-result)（Vue 3） - 别只改
.amap-sug-input的 z-index —— 它只是输入框，真正弹出的是.amap-sug-result
API 加载与安全密钥配置容易漏掉
高德 JSAPI 自 2023 年起强制校验 _AMapSecurityConfig.securityJsCode，否则控制台报错 SecurityJsCode is required，地图无法加载瓦片。
- 在引入高德 SDK 的
<script></script>标签前，必须先声明全局变量：window._AMapSecurityConfig = { securityJsCode: '你的安全密钥' }; - 安全密钥不是 AK（Access Key），需单独在 高德开放平台 → 应用管理 → 安全密钥 页面生成，绑定域名（如
localhost、yourdomain.com） - AK 仍要传进 SDK URL：
https://webapi.amap.com/maps?v=2.0&key=你的AK，但没 securityJsCode 就白搭
最容易被忽略的是：安全密钥和 AK 必须来自同一个应用，且域名白名单要完全匹配（http://localhost:8080 ≠ http://127.0.0.1:8080）。开发时多看控制台 Network 面板里 https://restapi.amap.com/v3/config/security 是否返回 200，这是验证配置是否生效的最快方式。
