React集成Mapbox时重复渲染两张地图的问题排查

可能的原因及对应解决方法 #

1. 缺失Mapbox官方样式文件 #

你的代码中注释掉了import "mapbox-gl/dist/mapbox-gl.css";，Mapbox地图组件依赖官方CSS来管控DOM元素的布局与显示，缺少样式会导致地图内部图层、控件等元素排版混乱，视觉上呈现出“两张地图”的效果。

解决方法：
取消注释该行，引入Mapbox官方样式：

import "mapbox-gl/dist/mapbox-gl.css";

2. 未清理Mapbox实例 #

在useEffect中创建了Mapbox实例，但未处理组件卸载时的销毁逻辑。若组件因React重渲染、Next.js Hydration等场景重新挂载，旧实例不会被销毁，新实例又会生成，最终页面出现多个地图。

解决方法：
修改useEffect，添加清理函数销毁地图实例：

useEffect(() => {
  const mapInstance = new mapboxgl.Map({
    container: mapContainer.current,
    style: "mapbox://styles/.....",
    center: [lng, lat],
    zoom: zoom,
    maxZoom: 14,
    minZoom: zoom,
  });
  setMap(mapInstance);

  // 组件卸载时销毁地图
  return () => {
    mapInstance.remove();
  };
}, []);

3. Next.js Hydration导致重复初始化 #

Next.js的SSR/SSG过程中，服务端渲染内容与客户端Hydration可能出现不一致，触发Mapbox重复初始化。

解决方法：
限制仅在客户端初始化地图：

useEffect(() => {
  if (typeof window === 'undefined') return; // 仅客户端执行

  const mapInstance = new mapboxgl.Map({
    container: mapContainer.current,
    style: "mapbox://styles/.....",
    center: [lng, lat],
    zoom: zoom,
    maxZoom: 14,
    minZoom: zoom,
  });
  setMap(mapInstance);

  return () => {
    mapInstance.remove();
  };
}, []);

4. 容器样式引发的视觉错觉 #

地图容器使用了position-absolute top-0 start-0 w-100 h-100，若父元素未设置position: relative，绝对定位的容器可能溢出或与其他元素重叠，造成“两张地图”的视觉假象。

解决方法：
给父容器添加相对定位样式：

return (
  <div style={{position: 'relative', width: '100%', height: '100vh'}}>
    <div
      className="position-absolute top-0 start-0 w-100 h-100"
      ref={mapContainer}
    />
  </div>
);

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