网络连接恢复时强制刷新Leaflet地图瓦片

我之前在做Leaflet+React的项目时，也碰到过一模一样的弱网场景问题——断网时拖动地图出现空白瓦片，恢复网络后那些空白区域死活不重新加载，试了invalidateSize、redraw甚至折腾setView都没用。后来研究了Leaflet的TileLayer底层逻辑，找到了几个靠谱的解决办法，分享给你：

方法一：针对性重新加载失败的瓦片 #

Leaflet的TileLayer内部会维护一个_tiles对象，存储当前视图内所有瓦片的状态。断网时加载失败的瓦片会被标记为未加载完成，我们可以遍历这个对象，找到失败的瓦片并强制重新加载：

// 假设你用useRef保存了react-leaflet的TileLayer组件实例
const tileLayerRef = useRef(null);

// 网络恢复时执行的函数
const handleNetworkOnline = () => {
  // 获取底层的Leaflet TileLayer实例
  const leafletTileLayer = tileLayerRef.current?.leafletElement;
  if (!leafletTileLayer) return;

  // 遍历所有缓存的瓦片
  Object.values(leafletTileLayer._tiles).forEach(tile => {
    // 判断瓦片是否加载失败（未加载完成且不在加载中）
    if (!tile.loading && !tile._layer._loaded) {
      // 移除页面上的空白瓦片元素
      tile.el.remove();
      // 重新触发该坐标瓦片的加载
      leafletTileLayer._addTile(tile.coords);
    }
  });
};

// 在组件挂载时监听网络恢复事件
useEffect(() => {
  window.addEventListener('online', handleNetworkOnline);
  return () => {
    window.removeEventListener('online', handleNetworkOnline);
  };
}, []);

方法二：通过修改URL强制刷新所有瓦片 #

如果不想逐个判断失败瓦片，也可以给瓦片URL加个随机参数（比如时间戳），让浏览器认为是新资源，从而重新请求所有瓦片：

const tileLayerRef = useRef(null);

const handleNetworkOnline = () => {
  const leafletTileLayer = tileLayerRef.current?.leafletElement;
  if (!leafletTileLayer) return;

  const originalUrl = leafletTileLayer.getUrl();
  // 给URL添加时间戳参数，绕过浏览器缓存
  const timestamp = Date.now();
  const newUrl = originalUrl.includes('?')
    ? `${originalUrl}&t=${timestamp}`
    : `${originalUrl}?t=${timestamp}`;
  
  // 更新TileLayer的URL并触发重绘
  leafletTileLayer.setUrl(newUrl);
  leafletTileLayer.redraw();
};

// 同样挂载时监听online事件
useEffect(() => {
  window.addEventListener('online', handleNetworkOnline);
  return () => window.removeEventListener('online', handleNetworkOnline);
}, []);

这个方法简单粗暴，但会重新加载当前视图内的所有瓦片，适合对性能要求不高的场景。

方法三：记录失败瓦片坐标，精准恢复 #

如果想更高效，只重新加载那些确实加载失败的瓦片，可以监听tileerror事件记录失败的坐标，网络恢复时针对性加载：

const tileLayerRef = useRef(null);
const missingTiles = useRef(new Set());

useEffect(() => {
  const leafletTileLayer = tileLayerRef.current?.leafletElement;
  if (!leafletTileLayer) return;

  // 监听瓦片加载失败事件，记录坐标
  const handleTileError = (e) => {
    const coordsKey = `${e.coords.x},${e.coords.y},${e.coords.z}`;
    missingTiles.current.add(coordsKey);
  };

  // 网络恢复时加载缺失的瓦片
  const handleOnline = () => {
    if (missingTiles.current.size === 0) return;
    missingTiles.current.forEach(key => {
      const [x, y, z] = key.split(',').map(Number);
      leafletTileLayer._addTile({ x, y, z });
    });
    missingTiles.current.clear();
  };

  leafletTileLayer.on('tileerror', handleTileError);
  window.addEventListener('online', handleOnline);

  return () => {
    leafletTileLayer.off('tileerror', handleTileError);
    window.removeEventListener('online', handleOnline);
  };
}, []);

这种方式只会重新加载真正失败的瓦片，性能最优，推荐在复杂场景下使用。

关键注意事项 #

• 如果用的是react-leaflet库，一定要通过ref.current.leafletElement获取底层的Leaflet原生实例，直接操作React组件是没用的；
• 测试时可以用浏览器开发者工具的Network面板，勾选Offline模拟断网，取消勾选模拟网络恢复，验证效果；
• 记得在组件卸载时移除事件监听，避免内存泄漏。

内容的提问来源于stack exchange，提问作者bdk0172