React-google-maps Circle组件不显示：同浏览器跨设备渲染异常

问题分析 #

你遇到的核心问题是Circle组件渲染时机与地图实例初始化不同步：部分浏览器中，Circle可能在地图API或地图实例未完全就绪时就完成渲染，导致无法正确绑定到地图；只有强制重绘时地图实例已就绪，Circle才能正常挂载，刷新后又回到初始不同步状态。

解决方案 #

以下是针对性的修复步骤：

• 改用useJsApiLoader严格控制API加载时机
  放弃LoadScript组件，用useJsApiLoader钩子明确监听API加载状态，确保只有API加载完成后才渲染地图组件。

• 通过地图onLoad回调控制Circle渲染
  利用GoogleMap的onLoad回调，确认地图实例初始化完成后再渲染Circle，避免提前渲染导致的绑定失败。

• 缓存Circle的props避免不必要的重绘
  将center和options这类静态数据提取为常量或用useMemo缓存，防止每次渲染生成新对象引发组件异常。

修改后的代码示例 #

import React, { useRef, useState, useMemo } from 'react';
import { GoogleMap, StandaloneSearchBox, Circle, useJsApiLoader } from '@react-google-maps/api';

const EndpointMap = () => {
  const searchBoxRefLocation = useRef(null);
  const mapRef = useRef(null);
  const apiKey = 'myKey';
  
  // 监听Google Maps API加载状态
  const { isLoaded } = useJsApiLoader({
    id: 'google-map-script',
    googleMapsApiKey: apiKey,
    libraries: ['places']
  });

  // 标记地图实例是否初始化完成
  const [mapReady, setMapReady] = useState(false);

  // 缓存Circle的静态属性，避免重复创建对象
  const circleCenter = useMemo(() => ({ lat: 49.2, lng: -123.2194 }), []);
  const circleOptions = useMemo(() => ({
    strokeColor: '#FF0000',
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: '#FF0000',
    fillOpacity: 0.1,
  }), []);

  // 地图加载完成后更新就绪状态
  const handleMapLoad = (map) => {
    mapRef.current = map;
    setMapReady(true);
  };

  if (!isLoaded) {
    return <div>加载地图中...</div>;
  }

  return (
    <div style={{ height: '100vh', width: '100vw' }}>
      <GoogleMap
        ref={mapRef}
        mapContainerStyle={{ height: '100vh', width: '100vw' }}
        center={{ lat: 49.3, lng: -123.2194 }}
        zoom={8}
        onLoad={handleMapLoad}
      >
        {/* 仅当地图就绪后渲染Circle */}
        {mapReady && (
          <Circle
            center={circleCenter}
            radius={10000}
            options={circleOptions}
          />
        )}
      </GoogleMap>
    </div>
  );
};

export default EndpointMap;

额外排查点 #

• 检查两台电脑的Chrome版本是否一致，若版本差异大，尝试升级到最新稳定版
• 确认浏览器是否禁用了Google Maps相关的JavaScript功能或插件
• 查看浏览器控制台是否有地图API加载失败的报错（比如API密钥权限问题）

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