地图容器必须显式设置宽高，否则白屏；Bootstrap中div默认内容撑开高度，百度地图JS API依赖父容器CSS尺寸，未设height会导致渲染区域为0×0而空白。
地图容器必须显式设置宽高，否则白屏
Bootstrap 的 div 默认是内容撑开高度，而百度地图 JS API 渲染时依赖父容器的 CSS 尺寸。如果只写 且没设 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）配置也容易出错：
调用百度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 直接用——都可能让地图在用户面前彻底“消失”。
