Next.js集成Google Maps JS API（高级标记）时initMap报错问题

你遇到的InvalidValueError: initMap is not a function间歇性报错，核心原因有两个：

1. 回调函数未全局暴露
   谷歌Maps API的callback=initMap参数要求initMap是挂载在全局window对象上的函数，但你的initMap定义在useEffect内部，属于组件局部函数，外部脚本无法访问。间歇性出现是因为脚本加载和useEffect执行的顺序不确定：如果脚本先加载完成，会找不到全局的initMap而报错；导航返回时脚本已缓存，useEffect的轮询能找到window.google，所以不会触发报错。

2. 双重等待逻辑冲突
   你同时使用了谷歌API的callback机制和自己的setInterval轮询，两种等待逻辑重复且容易出现时序问题，反而增加了出错概率。

下面是Next.js中集成Google Maps JavaScript API+Advanced Markers的标准实现，适配Next.js客户端渲染生命周期，避免全局污染：

import { useRef, useEffect } from 'react';
import Script from 'next/script';

const GoogleMap = ({ coords }) => {
  const mapContainer = useRef(null);

  // 地图初始化核心逻辑
  const initMap = () => {
    // 防御性检查：容器不存在或谷歌API未加载则终止
    if (!mapContainer.current || !window.google?.maps) return;

    // 创建地图实例
    const map = new window.google.maps.Map(mapContainer.current, {
      center: { lat: coords[0]?.lat ?? 0, lng: coords[0]?.lng ?? 0 },
      zoom: 15,
      mapId: "d2a1a27e40cc216a",
    });

    const bounds = new window.google.maps.LatLngBounds();

    // 批量添加Advanced Markers
    coords.forEach(coord => {
      if (!coord?.lat || !coord?.lng) return;

      const marker = new window.google.maps.marker.AdvancedMarkerView({
        map,
        content: buildContent(coord), // 替换为你的标记内容渲染函数
        position: { lat: coord.lat, lng: coord.lng },
        zIndex: 1,
      });

      bounds.extend(marker.position);
    });

    // 自动调整地图视野覆盖所有标记
    if (coords.length > 0) map.fitBounds(bounds);
  };

  // 处理客户端路由返回场景：脚本已加载时直接初始化
  useEffect(() => {
    if (window.google?.maps) {
      initMap();
    }
  }, [coords]);

  return (
    <>
      {/* 使用Next.js Script组件管理外部脚本加载 */}
      <Script
        src={`https://maps.googleapis.com/maps/api/js?key=你的API密钥&v=beta&libraries=marker`}
        strategy="lazyOnload" // 页面空闲时加载，不阻塞首屏
        onLoad={initMap} // 脚本加载完成后自动触发初始化
        onError={(err) => console.error('地图脚本加载失败:', err)}
      />
      {/* 地图容器 */}
      <div ref={mapContainer} className="h-full w-full" />
    </>
  );
};

// 示例：自定义标记内容函数（根据你的需求修改）
const buildContent = (coord) => {
  const div = document.createElement('div');
  div.className = 'custom-marker';
  div.innerHTML = `<span>${coord.name ?? '标记'}</span>`;
  return div;
};

export default GoogleMap;

• 利用Next.js Script组件的生命周期：通过onLoad回调确保脚本加载完成后再执行初始化，无需手动轮询，彻底避免时序问题。
• 避免全局函数污染：无需将initMap挂载到window，直接通过onLoad传递局部函数，符合React组件封装原则。
• 防御性编程：增加多层检查（容器存在、API加载完成、坐标有效），避免空值导致的报错。
• 适配客户端路由：通过useEffect监听coords变化，同时处理导航返回时脚本已缓存的场景，保证地图能重新初始化。
• 错误处理：添加onError回调捕获脚本加载失败的情况，方便调试。

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