地图一片空白，控制台却没有报错

现象

页面结构正常，地图容器的边框也在，里面什么都没有。 控制台干净，网络面板里甚至能看到瓦片请求成功返回。 有时窗口缩放一下就突然显示出来了。

八成是容器高度为零

三个库都要求容器有确定的高度。写 height: 100% 只在父元素高度确定时才生效， 如果父元素高度是 auto，百分比会退化成 0，地图初始化时读到的高度就是 0， 渲染缓冲区什么都没有。

/* 错误写法：body 没给高度，100% 直接失效 */
html, body { margin: 0; }
#map { height: 100%; }

/* 正确写法一：从根节点一路给高度 */
html, body { height: 100%; margin: 0; }
#map { height: 100%; }

/* 正确写法二：用 flex 让地图吃掉剩余空间 */
html, body { height: 100%; margin: 0; }
body { display: flex; flex-direction: column; }
header { flex: 0 0 48px; }
#map { flex: 1 1 auto; min-height: 0; }

第二种写法在真实项目里更稳，因为有页头页脚时不用算高度。 注意 min-height: 0，漏了它 flex 子项不会被压缩，内容一多就把地图挤出去。

窗口缩放才显示：初始化太早

地图在隐藏状态（弹窗未打开、标签页未激活、折叠面板收起）时初始化， 容器尺寸读到 0。之后容器显示出来，地图仍然以为自己是 0 大小。

正确的做法是等容器可见之后再初始化；如果没法控制时序，就在容器显示时调一次重算方法。

库没加载成功

CDN 被拦或超时，脚本标签失败但页面不报错。 判断方法很简单：在控制台直接敲库的全局变量名。

typeof L        // 'undefined' 表示 Leaflet 没加载上
typeof ol       // 'undefined' 表示 OpenLayers 没加载上
typeof Cesium   // 'undefined' 表示 Cesium 没加载上

确认没加载上之后，把 CDN 地址换成可访问的镜像，或者把库下载到本地用相对路径引用。 生产环境建议自己托管，避免第三方 CDN 抖动。

CSS 层级把画布压住了

地图渲染出来了，但被一个绝对定位的遮罩、或者 z-index 更大的兄弟元素盖住。 在地图容器上临时加一个红色边框，就能判断它到底有没有尺寸、有没有被盖。

#map { outline: 2px solid red; }

能看到红框但没有地图，是渲染问题；红框都没有，是布局问题；红框在但被别的东西挡着， 是层级问题。这三步能把九成情况分开。

排查顺序

1. 给容器加红色 outline，确认它有没有尺寸
2. 没有尺寸 → 查父级高度链，改用 flex
3. 有尺寸但白 → 查库是否加载（控制台敲全局变量）
4. 库正常但仍白 → 查是否初始化过早，容器可见后调一次重算方法
5. 以上都正常 → 查 CSS 层级和遮罩