React多实例Google Maps组件API重复加载报错及密钥优化问题

一、解决「Google Maps JavaScript API重复引入」错误 #

核心思路是全局仅加载一次Google Maps脚本，手动实现单例加载逻辑，无需依赖第三方npm模块：

• 封装全局加载函数，维护加载状态：
  在组件外部（比如单独的google-maps-loader.js文件或组件顶部）定义单例逻辑：

  // 全局标记API是否已加载
  let mapsApiLoaded = false;
  let mapsApiPromise;
  
  export function loadGoogleMaps(apiKey) {
    // 已加载直接返回已就绪的Google对象
    if (mapsApiLoaded) {
      return Promise.resolve(window.google);
    }
    // 正在加载中，返回同一个Promise
    if (mapsApiPromise) {
      return mapsApiPromise;
    }
    // 首次加载，创建Promise并插入脚本
    mapsApiPromise = new Promise((resolve) => {
      const script = document.createElement('script');
      script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}&libraries=places`; // 根据需求添加所需libraries
      script.async = true;
      script.defer = true;
      script.onload = () => {
        mapsApiLoaded = true;
        resolve(window.google);
      };
      document.head.appendChild(script);
    });
    return mapsApiPromise;
  }
  

• 组件内调用加载函数：
  在函数组件的useEffect或类组件的componentDidMount中调用，确保每个组件实例复用同一个加载结果：

  import { loadGoogleMaps } from './google-maps-loader';
  
  function MapComponent() {
    const [map, setMap] = useState(null);
    const apiKey = process.env.REACT_APP_GOOGLE_MAPS_API_KEY;
  
    useEffect(() => {
      loadGoogleMaps(apiKey).then((google) => {
        // 初始化地图逻辑，创建Map实例
        const mapInstance = new google.maps.Map(document.getElementById('map'), {
          center: { lat: -34.397, lng: 150.644 },
          zoom: 8,
        });
        setMap(mapInstance);
      });
      // 清理函数：销毁地图实例，但不要移除全局脚本
      return () => {
        if (map) {
          map = null;
        }
      };
    }, [apiKey]);
  
    return <div id="map" style={{ width: '100%', height: '400px' }}></div>;
  }
  

• 页面切换处理：由于脚本是全局加载的，切换页面时不会重复插入，只要组件复用同一个加载函数，就不会触发重复引入错误。

二、Google API密钥的最佳实践 #

• 绝对不能硬编码密钥，必须存入.env文件，避免密钥暴露在前端代码中被滥用。
• 具体操作步骤：
  1. 在项目根目录创建.env文件，添加如下内容（替换为你的实际密钥）：

     REACT_APP_GOOGLE_MAPS_API_KEY=your_actual_api_key_here
     

     注意：变量名必须以REACT_APP_开头，React才会自动识别；同时把.env加入.gitignore，禁止提交到版本控制。
  2. 在组件中直接读取环境变量：

     const apiKey = process.env.REACT_APP_GOOGLE_MAPS_API_KEY;
     

• 生产环境优化：部署时可在平台（如Vercel、Netlify）的环境变量设置中配置密钥，无需上传.env文件到服务器，进一步提升安全性。

三、Loader的调用策略 #

• 必须仅调用一次Loader并全局存储加载状态，也就是前面实现的单例加载方案。这种方式无需重构现有组件核心逻辑，只需要替换原来的API加载代码即可，完美适配你的需求。所有组件实例共享同一个加载Promise，既避免重复加载API，又能保证每个组件都能获取到Google Maps全局对象。

内容的提问来源于stack exchange，提问作者The Old County