解决 Leaflet.js 地图容器高度为 0 导致地图无法显示的问题

一、问题具体表现与排查定位

当 Leaflet 地图容器的高度折叠为 0 时，浏览器无法为地图分配任何渲染面积。由于 Leaflet 的底层实现是将瓦片网格（TileLayer）、矢量标注（Path/Marker）以及控制面板（Controls）全部置于 position: absolute 的图层窗格（Pane）内，这些脱离常规文档流的绝对定位元素不会像普通文本或图片那样撑大父级 <div id="map"> 容器。

在实际项目中，该故障通常表现为以下几种典型症状：

• 完全空白或呈 0 像素线条：页面上预留的地图区域完全空白，审查元素时发现 #map 节点的盒模型中 height 计算值为 0px。
• 仅加载单块左上角瓦片：在隐藏标签页或弹窗中初始化地图，切换显示后地图区域仅在左上角出现一块或两块残缺瓦片，其余区域全为灰色。
• 网络面板无瓦片请求：打开浏览器控制台 Network 面板，未见任何 openstreetmap.org 等瓦片源的图片网络请求发出。

通过浏览器开发者工具可以快速确认容器高度是否为 0。按下 F12 打开 DevTools，在 Elements 面板选中地图容器，查看 Computed（计算样式）中的 height。同时，在 Console（控制台）中直接执行以下自检脚本：

// 检查容器实际物理像素宽高
const mapDiv = document.getElementById('map');
console.log('容器 clientHeight:', mapDiv.clientHeight);
console.log('容器 offsetHeight:', mapDiv.offsetHeight);

// 检查 Leaflet 内部测定的视口尺寸
if (window.map) {
  console.log('Leaflet 视口尺寸:', window.map.getSize());
}

若输出的 clientHeight 为 0，或者 map.getSize() 返回 Point(0, 0)，即可 100% 确认问题由容器尺寸缺失导致。依照下图所示的标准流程进行分流定位：

图 1：Leaflet 地图容器高度为 0 问题的定位诊断与排查路径

二、原因一：CSS 盒模型中百分比高度继承链断裂

在许多网页中，开发者习惯直接为地图容器设置 height: 100%，希望地图填满整个页面或父区域。然而在标准 CSS 盒模型中，子元素若要按百分比计算高度，其包含块（父容器）必须具备明确的计算高度值。

在 HTML 标准中，<html> 与 <body> 标签的默认高度为 auto。当父元素高度为 auto 时，规范规定子元素的百分比高度将解析为 auto。而由于地图容器内部没有流式内容，auto 计算出的最终结果就是 0px。

图 2：CSS 百分比高度继承链断裂机理与贯通修复对比

修复方法 1：贯通整个祖先链路的 100% 高度

如果希望地图容器自适应填满浏览器视口或全屏展示，必须从根节点 html 开始，顺次将所有祖先节点的高度都声明为 100%：

/* 补齐从根节点到地图容器的完整高度链 */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

/* 若中间存在包装容器，也必须设置 height: 100% */
#app, .page-wrapper {
  height: 100%;
}

#map {
  width: 100%;
  height: 100%;
}

修复方法 2：使用视口单位（vh）或显式像素（px）

如果不想逐级修改上层祖先容器的样式，可以直接使用 CSS3 视口单位 vh（Viewport Height）或固定像素值。100vh 能够越过中间所有父节点，直接参照浏览器可视窗口高度进行计算：

/* 方案 A：视口全屏方案 */
#map {
  width: 100%;
  height: 100vh;
}

/* 方案 B：固定尺寸卡片方案 */
.map-card #map {
  width: 100%;
  height: 500px;
  min-height: 400px;
}

三、原因二：动态组件与隐藏容器导致的渲染时机脱节

第二类高频原因发生在选项卡（Tabs）、模态弹窗（Modal/Dialog）、折叠面板（Accordion）或抽屉（Drawer）等动态 UI 组件中。这类组件在初始渲染时，处于隐藏状态，其对应的 DOM 通常被应用了 display: none。

在 display: none 的元素上，浏览器渲染引擎不会生成几何排版盒（RenderBox），此时容器的 offsetWidth 和 offsetHeight 均为 0。如果页面脚本在此时就执行了 L.map('map', ...)，Leaflet 获取到的容器宽度与高度均为 0。

当用户点击按钮打开弹窗或切换至地图选项卡时，容器的 CSS 属性变更为 display: block 并获得了实际高度。然而，Leaflet 内部不会主动轮询检测外部容器的变化，其视口缓存仍停留在初始的 0x0，从而导致地图区域灰屏，或者只能在左上角加载少量瓦片。

图 3：隐藏容器初始化时序脱节与 invalidateSize() 修复过程

核心修复 API：map.invalidateSize()

Leaflet 提供了官方 API map.invalidateSize(options)。该方法会强制 Leaflet 重新调用 container.getBoundingClientRect()，重新计算视口大小，并请求当前视野内缺失的网格瓦片。

关键在于触发调用的时机：必须在容器已经变为可见且完成了 CSS 展开过渡动画之后再调用。

场景 1：原生 JS / 选项卡切换监听

// 假设施加了 Tab 切换监听
const tabBtn = document.getElementById('tab-map');
tabBtn.addEventListener('click', () => {
  // 显示包含地图的容器
  document.getElementById('map-container').style.display = 'block';
  
  // 在 DOM 渲染更新后校准尺寸
  setTimeout(() => {
    map.invalidateSize();
  }, 100);
});

场景 2：Bootstrap 模态框 / 组件库事件监听

// Bootstrap 5 模态弹窗完全展开事件 shown.bs.modal
const myModalEl = document.getElementById('mapModal');
myModalEl.addEventListener('shown.bs.modal', () => {
  // 动画完全结束、容器拥有真实尺寸后调用
  map.invalidateSize();
});

场景 3：现代化自动监测方案（ResizeObserver）

为了避免在每个弹窗和 Tab 切换处手动编写事件监听，推荐使用现代浏览器内置的 ResizeObserver。只要地图容器的宽高发生变化，就会自动触发 invalidateSize()：

const mapContainer = document.getElementById('map');
const resizeObserver = new ResizeObserver(() => {
  if (mapContainer.clientHeight > 0) {
    map.invalidateSize();
  }
});

// 启动对地图容器尺寸变化的持续观察
resizeObserver.observe(mapContainer);

四、原因三：Flexbox / Grid 弹性布局中的高度坍塌

在现代化后台管理界面的上下分栏架构中（例如顶部导航固定高度，剩余空间全部由地图填充），通常使用 display: flex; flex-direction: column;。若配置不当，也会出现高度为 0 的情况。

在 Flex 容器中，未设置 height: 100% 的垂直弹性列无法拉伸；另外，Flex 项目的默认属性是 min-height: auto，有时会阻止容器收缩或正确计算。针对 Flex 布局的标准写法如下：

/* 外层主容器采用 flex 纵向排版 */
.admin-layout {
  display: flex;
  flex-direction: column;
  height: 100vh;
}

.header {
  height: 60px;
  flex-shrink: 0;
}

.content-body {
  display: flex;
  flex: 1;           /* 撑满剩余全部垂直空间 */
  min-height: 0;     /* 关键：允许 flex 项目尺寸自适应收缩 */
}

#map {
  width: 100%;
  height: 100%;
  flex: 1;
}

五、排查与修复决策全景总结

面对地图容器高度为 0 的不同业务场景，下表与决策图整理了最适合的工程方案：

图 4：Leaflet 地图容器高度故障排查与修复决策矩阵

六、综合实战示例：可运行的完整单文件代码

以下提供一个包含样式继承与动态弹窗校准的完整单文件示例，读者可直接保存为 HTML 文件进行验证：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Leaflet 容器高度修复验证示例</title>
  <!-- 1. 务必正确引入 Leaflet 核心样式表 -->
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
  <style>
    html, body {
      height: 100%;
      margin: 0;
      padding: 0;
    }
    .wrapper {
      display: flex;
      flex-direction: column;
      height: 100%;
    }
    .nav-bar {
      height: 50px;
      background: #456581;
      color: #fff;
      display: flex;
      align-items: center;
      padding: 0 16px;
    }
    /* 关键：赋予地图容器明确的高度与伸缩比例 */
    #map {
      flex: 1;
      width: 100%;
      min-height: 0;
    }
  </style>
</head>
<body>
  <div class="wrapper">
    <div class="nav-bar">Leaflet 地图容器高度校验正常示例</div>
    <div id="map"></div>
  </div>

  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
  <script>
    // 初始化地图实例
    const map = L.map('map').setView([39.9042, 116.4074], 12);

    // 加载标准瓦片图层
    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      maxZoom: 19,
      attribution: '© OpenStreetMap'
    }).addTo(map);

    // 窗口尺寸变化自适应
    window.addEventListener('resize', () => {
      map.invalidateSize();
    });
  </script>
</body>
</html>

七、常见连带陷阱与注意事项