React应用中@react-google-maps/api加载的Google Map全灰问题排查

我在开发React应用时，使用@react-google-maps/api库集成Google Maps组件，已按要求完成配置，控制台与网络面板无明显错误，但地图显示为全灰色区域，无法加载预期的地图瓦片及内容。

我的代码如下：

import React from "react";
import { GoogleMap, LoadScript, Marker } from "@react-google-maps/api";
import env from "react-dotenv";

const googleApiKey = env.REACT_APP_GOOGLE_API_KEY;

const center = {
  lat: 39.3391178,
  lng: -9.3253742,
};

const zoom = 15;

function Map() {
  const onLoad = (map) => {
    console.log("Map loaded:", map);
  };

  const onUnmount = (map) => {
    console.log("Map unmounted:", map);
  };

  return (
    <section className="h-[400px] pb-16 px-2 lg:px-16">
      <div className="container mx-auto h-full">
        <LoadScript googleMapsApiKey={googleApiKey}>
          <GoogleMap
            onLoad={onLoad}
            onUnmount={onUnmount}
            mapContainerClassName="w-full h-full"
            mapTypeId="satellite"
            zoom={zoom}
            center={center}
          >
            <Marker position={center} />
          </GoogleMap>
        </LoadScript>
      </div>
    </section>
  );
}

export default Map;

以下是排查和解决步骤：

• 确认API密钥权限
  确保你的Google API密钥已启用Maps JavaScript API和Satellite Maps API（代码中使用了satellite地图类型）。登录Google Cloud控制台，进入API库检查这两个API的启用状态；同时检查密钥的访问限制（如IP、HTTP referrer）是否与当前开发环境匹配，避免请求被拦截。

• 验证API密钥是否正确读取
  在组件中添加日志打印，确认googleApiKey是否获取到有效值：

  console.log("当前API密钥:", googleApiKey);
  

  如果输出undefined，检查react-dotenv配置：根目录需有.env文件，变量名必须是REACT_APP_GOOGLE_API_KEY，且修改.env后需重启开发服务器。

• 检查地图容器尺寸
  临时给mapContainerClassName添加背景色测试容器是否正常渲染：

  mapContainerClassName="w-full h-full bg-red-500"
  

  如果红色区域正常显示，说明容器尺寸没问题；若未显示，检查父级容器的h-full是否生效，可尝试给上层容器设置明确的像素高度（如height: 400px）。

• 切换地图类型排查
  将mapTypeId="satellite"改为mapTypeId="roadmap"，测试普通地图能否加载。若普通地图正常，说明Satellite API权限不足或未启用；若仍为灰色，问题大概率出在密钥或容器配置上。

• 监听脚本加载状态
  给LoadScript添加错误回调，捕获脚本加载失败的信息：

  <LoadScript
    googleMapsApiKey={googleApiKey}
    onError={(err) => console.error("地图脚本加载失败:", err)}
  >
    {/* ... */}
  </LoadScript>
  

  根据错误提示针对性解决（如密钥无效、API未启用等）。

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