地图容器必须显式设置宽高，否则白屏；Bootstrap中div默认内容撑开高度，百度地图JS API依赖父容器CSS尺寸，未设height会导致渲染区域为0×0而空白。

地图容器必须显式设置宽高，否则白屏

Bootstrap 的 div 默认是内容撑开高度，而百度地图 JS API 渲染时依赖父容器的 CSS 尺寸。如果只写 <div id="map"></div> 且没设 height，地图实例初始化成功但渲染区域为 0×0，结果就是一片空白。

正确做法是在 Bootstrap 栅格内用内联样式或 class 控制尺寸：

• style="width: 100%; height: 400px;" 是最直接、兼容性最好的方式
• 避免用 h-100 类——它只在父元素有明确高度时才生效，而常见布局中父 .row 或 .col 往往没有设定高度
• 响应式场景下可配合媒体查询，比如小屏设 height: 300px，大屏设 height: 500px

Vue 项目里用 vue-baidu-map 要配对版本和 AK

如果你用的是 Vue（尤其 Vue 3），vue-baidu-map 并非原生支持 Vue 3 的响应式系统。v0.21.x 及更早版本只适配 Vue 2；Vue 3 需改用社区维护的 vue-baidu-map-v3 或自行封装 Composition API 逻辑。

AK（Access Key）配置也容易出错：

百度文档解析vlm-parser

调用百度PaddleOCR‑VL大模型API，支持PDF、Word、PPT、图片等多格式文档解析，精准识别印刷体、手写体、表格、公式、图表、印章等复杂元素，支持100+语言，可处理不规则布局和跨页长文档。触发词：文档解析、VLM解析、大模型OCR、PaddleOCR、多模态文档、手写识别、公式识别、复杂版面。

下载

• 必须在百度地图开放平台创建「浏览器端」类型应用，不能选「服务端」
• Referer 白名单要填完整域名，如 http://localhost:8080/*、https://yourdomain.com/*，漏掉 /* 或协议会导致 401 错误
• 启用服务必须勾选「JavaScript API」，否则加载脚本时控制台报 ak invalid

定位失败常见原因：权限、HTTPS、坐标偏移

调用 BMap.Geolocation 或 bm-geolocation 组件后无响应或返回错误，大概率是以下三者之一：

• 页面未通过 HTTPS 提供服务：现代浏览器强制要求 navigator.geolocation 在安全上下文（HTTPS 或 localhost）中运行，HTTP 协议下直接静默拒绝
• 用户首次访问未授予权限：部分浏览器（如 Safari、Edge）会缓存“拒绝”状态，需手动进设置重置站点权限
• 百度坐标系（BD-09）与 GPS 原始坐标（WGS-84）不一致：直接把手机获取的经纬度传给百度地图标注，位置会偏移 500 米以上；必须用 BMap.Convertor.translate() 转换，或后端调用百度逆地理编码接口做纠偏

Bootstrap 模态框（Modal）里地图拖不动？重新初始化

在 Bootstrap 的 modal 中动态插入百度地图时，常出现拖拽卡顿、缩放失灵、地图只显示左上角四分之一等问题。根本原因是地图容器在 modal 隐藏状态下初始化，DOM 尺寸计算异常。

解决办法不是改 CSS，而是监听 modal 事件：

• 在 shown.bs.modal 事件回调中调用 map.centerAndZoom() 或 map.refresh()
• 若用 vue-baidu-map，应在 v-if="showModal" 控制组件挂载，而非 v-show（后者只是 display: none，地图实例仍在运行但不可见）
• 避免在 modal 的 fade 动画进行中初始化地图，建议加 setTimeout(..., 100) 确保 DOM 渲染完成

地图集成里最隐蔽的问题，往往不在 JS 逻辑，而在容器生命周期和坐标系认知偏差。一个没设 height 的 div，一次没填对的 Referer，或者把 WGS-84 当 BD-09 直接用——都可能让地图在用户面前彻底“消失”。