在使用 `@react-google-maps/api` 时，`` 等叠加层组件可能因地图初始化时机问题而无法正常渲染，尤其在部分设备或浏览器中表现不一致；本文提供基于 `useeffect` 的延迟挂载方案，并详解根本原因与最佳实践。

、、 等叠加层组件依赖于底层 Google Maps JavaScript API 的 Map 实例已完全就绪。然而， 组件在首次挂载时可能存在渲染竞态（render race）：其内部 map 实例尚未完成初始化，但子组件（如 ）已尝试挂载并绑定到未就绪的地图对象上，导致静默失败——无报错、无渲染，且在页面刷新后重现。

直接将 写在 内部 JSX 中（如原始代码所示）是反模式，因为该写法无法确保子组件仅在 map 实例可用后才实例化。

✅ 正确做法是：利用 onLoad 回调或 useEffect + ref 显式监听地图就绪状态，并条件性渲染叠加层：

Google AI Mode Search

使用本地Google Cookie在Google AI模式中搜索，实时获取体育比分、股票价格、新闻、天气和AI摘要。

下载

import React, { useRef, useState, useEffect } from 'react';
import { GoogleMap, LoadScript, Circle } from '@react-google-maps/api';

const EndpointMap = () => {
  const mapRef = useRef<google.maps.map null>(null);
  const [isMapLoaded, setIsMapLoaded] = useState(false);
  const apiKey = 'your-api-key';

  return (
    <loadscript googlemapsapikey="{apiKey}" libraries="{['places']}"><div style="{{" height: width:>
        <googlemap ref="{mapRef}" mapcontainerstyle="{{" height: width: center="{{" lat: lng: zoom="{8}" onload="{(map)"> {
            mapRef.current = map;
            setIsMapLoaded(true); // ✅ 地图加载完成，触发状态更新
          }}
        >
          {/* ✅ 仅在地图就绪后渲染 Circle */}
          {isMapLoaded && (
            <circle center="{{" lat: lng: radius="{10000}" options="{{" strokecolor: strokeopacity: strokeweight: fillcolor: fillopacity:></circle>
          )}
        </googlemap>
</div>
    </loadscript>
  );
};

export default EndpointMap;</google.maps.map>

⚠️ 注意事项：

• 避免 setTimeout 延迟 hack：答案中建议的 500ms 延迟虽偶现有效，但不可靠（网络波动、设备性能差异会导致失效），应优先使用 onLoad 这一官方支持的生命周期回调；
• ref 与 onLoad 需配合使用：onLoad 是唯一保证 map 实例已创建并可安全操作的时机，ref 则用于后续手动调用（如 panTo、fitBounds）；
• 确保 libraries 正确声明：Circle 不依赖 places 库，但若同时使用 StandaloneSearchBox，则需保留 ['places']；否则可精简为 []；
• 服务端渲染（SSR）兼容性：@react-google-maps/api 不支持 SSR，务必确保组件仅在客户端执行（如配合 dynamic + ssr: false 在 Next.js 中使用）。

总结： 渲染失败的本质是组件挂载早于 Google Maps 实例就绪。通过 onLoad 回调驱动状态更新，并条件渲染叠加层，可 100% 解决跨设备/跨浏览器的不一致问题，这是官方推荐且生产环境验证的最佳实践。