React中异步使用@googlemaps/js-api-loader：无效密钥未触发异常捕获

我在React中异步加载Google Maps API的代码如下：

const loadGoogleInstance = async () => {
  try {
    const google = new Loader({
      apiKey: "sdfsd", //传入无效密钥测试错误处理
      version: "weekly",
      libraries: [],
      region: "GR",
    });

    await google.load();

    setGoogleInstance(google);
  } catch (error) {
    console.log("Google Maps API failed to load", error);
    alert("Google Maps API failed to load");
  }
};

useEffect(() => {
  if (isAuthenticated) loadGoogleInstance();
  return () => {
    setGoogleInstance(null);
  };
}, [isAuthenticated]);

我传入无效API密钥测试错误处理，按理应该返回错误Promise并被catch块捕获，但实际仅输出警告日志：

Google Maps JavaScript API warning: InvalidKey https://developers.google.com/maps/documentation/javascript/error-messages#invalid-key

请问这是什么原因？

核心原因 #

Google Maps JavaScript API的无效密钥错误默认只会触发警告而非抛出异常，这是API本身的设计逻辑：它允许加载基础框架（不启用核心服务），不会主动终止加载流程，因此google.load()的Promise不会进入rejected状态，自然无法被catch块捕获。

如何捕获这类错误 #

要捕获无效密钥这类API级别的错误，需要手动监听Google Maps的全局错误事件：

方式1：注册authFailure全局事件

在加载完成后添加认证失败监听，主动抛出错误让catch块捕获：

const loadGoogleInstance = async () => {
  try {
    const google = new Loader({
      apiKey: "sdfsd",
      version: "weekly",
      libraries: [],
      region: "GR",
    });

    await google.load();
    // 监听认证失败事件
    google.maps.event.addListener(window, 'authFailure', () => {
      throw new Error('Google Maps API 无效密钥或认证失败');
    });

    setGoogleInstance(google);
  } catch (error) {
    console.log("Google Maps API failed to load", error);
    alert("Google Maps API failed to load");
  }
};

方式2：结合Loader的onerror参数与Promise包装

通过Promise包装加载流程，同时监听onerror和authFailure事件：

const loadGoogleInstance = async () => {
  try {
    await new Promise((resolve, reject) => {
      const google = new Loader({
        apiKey: "sdfsd",
        version: "weekly",
        libraries: [],
        region: "GR",
        callback: resolve,
        onerror: reject // 捕获加载级错误
      });

      google.load();
      // 额外监听认证失败事件
      google.maps?.event?.addListener(window, 'authFailure', () => {
        reject(new Error('Google Maps API 认证失败'));
      });
    });

    const google = window.google;
    setGoogleInstance(google);
  } catch (error) {
    console.log("Google Maps API failed to load", error);
    alert("Google Maps API failed to load");
  }
};

补充说明 #

• 只有网络故障、API服务不可用这类会中断加载流程的错误，才会让google.load()的Promise进入rejected状态；
• authFailure是官方提供的专门用于捕获密钥无效、权限不足等认证问题的事件。

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