React中使用@googlemaps/js-api-loader报‘google未定义’错误

问题场景 #

我基于Advanced Marker开发Google Map组件，原本通过index.html里的script标签引入Google Maps API，后来改用@googlemaps/js-api-loader包实现，核心代码如下：

import React, { useEffect, useState } from "react";
import { v4 as uuidv4 } from "uuid";
import { createRoot } from "react-dom/client";
import Typography from "@mui/material/Typography";
import busTopViewImage from "../assets/bus-top-view.png";
import { Grid } from "@mui/material";
import { Loader } from "@googlemaps/js-api-loader";

const Marker = ({ text, backgroundColor }) => {
  return (
    <Grid
      container
      justifyContent="stretch"
      alignItems="center"
      direction="column"
    >
      <img src={busTopViewImage} alt="Bus Marker" />
      {text && backgroundColor && (
        <Grid
          item
          style={{
            backgroundColor: backgroundColor,
            borderRadius: "10px",
            padding: "0 0.5rem",
          }}
        >
          <Typography variant="body1" color="white">
            {text}
          </Typography>
        </Grid>
      )}
    </Grid>
  );
};
interface ICenter {
  lat: number | string;
  lng: number | string;
}

const Map = ({ center, markers }: { center: ICenter }) => {
  const [mapId, setMapId] = useState<string | null>(null);

  useEffect(() => {
    async function initMap() {
      const loader = new Loader({
        apiKey: "YOUR_API_KEY", // 需替换为实际API密钥
        version: "weekly",
      });
      const { Map } = await loader.importLibrary("maps");
      const { AdvancedMarkerElement } = await loader.importLibrary("marker");

      const map = new Map(document.getElementById(mapId) as HTMLElement, {
        center,
        zoom: 14,
        mapId: `${mapId}${100 + Math.floor(100 * Math.random())}`,
      });
      let mapMarkers = [];
      for (let markerData of markers) {
        const markerComponent = document.createElement("div");
        const root = createRoot(markerComponent);
        
        root.render(<Marker {...markerData.marker} />);
        const m = new AdvancedMarkerElement({
          map,
          position: markerData.coordinates,
          content: markerComponent,
        });
        mapMarkers.push(m);
      }
    }
    if (mapId) {
      initMap();
    }
  }, [mapId, markers]);

  useEffect(() => {
    setMapId(uuidv4());
  }, []);
  if (mapId)
    return <div id={mapId} style={{ width: "100%", height: "100%" }}></div>;
  else return <></>;
};
export default Map;

运行后控制台抛出错误：

Uncaught (in promise) ReferenceError: google is not defined
    initMap Map.tsx:37
    Map Map.tsx:70
    React 9
    workLoop scheduler.development.js:266
    flushWork scheduler.development.js:239
    performWorkUntilDeadline scheduler.development.js:533
    js scheduler.development.js:571
    js scheduler.development.js:633
    __require chunk-ROME4SDB.js:11
    js index.js:6
    __require chunk-ROME4SDB.js:11
    React 2
    __require chunk-ROME4SDB.js:11
    js React
    __require chunk-ROME4SDB.js:11
    js React
    __require chunk-ROME4SDB.js:11
    <anonymous> react-dom_client.js:38

问题根源 #

排查后确认错误来自组件迁移时的两处疏漏：

• 页面中仍保留了旧的本地Map组件，且相关导入路径未更新，旧组件依赖全局google对象，但我已经移除了index.html中引入Google Maps API的script标签
• 旧组件未被清理，依然在尝试访问已不存在的全局google变量

解决步骤 #

1. 清理旧组件与无效导入

   • 删除项目中未使用的旧版本地Map组件文件
   • 遍历所有导入Map组件的文件，确保导入路径指向新的、使用@googlemaps/js-api-loader的组件

2. 验证新组件逻辑

   • 确保Loader初始化时已正确配置API密钥
   • 确认所有Google Maps相关对象（如Map、AdvancedMarkerElement）均通过loader.importLibrary获取，避免直接访问全局google对象

3. 环境校验

   • 确认项目已正确安装@googlemaps/js-api-loader依赖（执行npm install @googlemaps/js-api-loader或yarn add @googlemaps/js-api-loader）
   • 确保index.html中已无旧的Google Maps API script标签（新组件通过loader按需加载API，无需全局引入）

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