react-leaflet首次加载瓦片渲染异常 调整窗口后恢复正常

问题根因 #

所有调整窗口大小后恢复正常的瓦片加载异常，本质都是首次触发尺寸计算时，地图容器尚未完成最终布局，Leaflet拿到的容器尺寸错误，导致瓦片加载范围计算出现偏差，仅加载了错误尺寸范围内的少量瓦片。

已尝试方案失效原因 #

你之前测试的全场景map.invalidateSize()调用之所以没有效果，是因为调用时机过早：不管是首次渲染useEffect、地图load事件触发时，浏览器都还没完成DOM重排，此时读取到的容器宽高是未完成布局的错误值，重算尺寸自然不生效。

可落地修复方案 #

• 延迟触发尺寸重算，给浏览器留出DOM布局计算的时间，参考实现：

import { useEffect } from 'react';
import { useMap } from 'react-leaflet';

function MapResizeFix() {
  const map = useMap();
  useEffect(() => {
    // 延迟200-300ms等容器布局稳定后再重算，可根据项目实际渲染速度调整时长
    const resizeTimer = setTimeout(() => {
      map.invalidateSize();
    }, 300);
    return () => clearTimeout(resizeTimer);
  }, [map]);
  return null;
}
// 将该组件放在MapContainer组件内部作为子组件即可生效

• 如果地图放置在Tabs标签页、折叠面板、模态弹窗这类默认隐藏/带展开动画的组件内，不要在组件挂载阶段调用重算方法，要等容器完全展开、显示动画结束、可见状态切换完成的回调里再执行map.invalidateSize()。
• 排查地图容器及所有父级元素的CSS：确认所有层级元素在地图初始化时都有明确的非0高度，避免出现height:100%继承链断裂、初始化时父元素高度为0后续被内容撑开的情况；如果是动态计算容器高度的场景，要等高度值计算完成并赋值给容器DOM后，再触发尺寸重算。
• 排查全局样式、组件库默认样式是否覆盖了Leaflet内置类的样式：重点检查.leaflet-container、.leaflet-tile-container类名对应的元素，不要被额外设置错误的position、transform、overflow、宽高属性。
• React 18严格模式下useEffect会双执行，可能导致地图实例重复初始化出现尺寸异常，可临时关闭严格模式验证，若确认是该问题，给地图实例初始化逻辑加单例判断即可。

效果参考 #

异常加载状态：

修复后正常加载状态：

内容的提问来源于stack exchange，提问作者Fabrizio Paolo Petrelli