Android应用更新后Google Maps API报NotLoadingAPIFromGoogleMapsError故障排查

问题背景 #

应用此前使用Google Maps API运行正常，更新Android版本后出现地图空白，提示“Oops! Something went wrong.”，网页版完全正常，仅Android端（HTML/JS与网页版一致）报错。JavaScript控制台显示NotLoadingAPIFromGoogleMapsError，但实际加载脚本为：

<script src="https://www.google.com/jsapi"></script>
<script src="https://maps.googleapis.com/maps/api/js?key=...."></script>

另有同加载方式的Android应用可正常运行，曾尝试添加&v=weekly&libraries=marker短暂解决，但问题再次复现。

可能原因 #

1. 旧jsapi加载器冲突：https://www.google.com/jsapi是Google的旧版加载器，当前Maps API已无需依赖它，WebView环境下该脚本可能干扰API的正常加载流程，导致API未从指定域名加载。
2. WebView缓存干扰：WebView缓存了错误的API加载路径或资源，即使脚本地址正确，实际请求仍被重定向到错误来源。
3. 内容安全策略（CSP）限制：Android WebView的CSP设置不当，阻止了Maps API相关资源的加载，触发域名校验错误。
4. API版本兼容性波动：使用v=weekly会自动更新到最新测试版，部分版本可能与WebView环境存在临时兼容问题，导致问题复发。

解决办法 #

• 移除旧jsapi脚本：直接删除<script src="https://www.google.com/jsapi"></script>，仅保留maps.googleapis.com的API加载脚本。官方早已弃用旧加载器，Web环境下无需依赖它。
• 强制清除WebView缓存：在Android代码初始化WebView时添加缓存清理逻辑：

  webView.clearCache(true);
  webView.clearHistory();
  

• 配置正确的CSP：在HTML头部添加CSP meta标签，允许加载Google Maps相关资源：

  <meta http-equiv="Content-Security-Policy" content="default-src 'self' https://maps.googleapis.com https://maps.gstatic.com; script-src 'self' https://maps.googleapis.com 'unsafe-inline' 'unsafe-eval'; style-src 'self' https://fonts.googleapis.com 'unsafe-inline';">
  

  根据实际需求调整规则，确保允许加载地图脚本、瓦片、图标等资源。
• 固定API稳定版本：将&v=weekly替换为具体稳定版本号（如&v=3.54，可参考官方稳定版列表），避免测试版本的兼容波动。
• 检查WebView核心设置：确保WebView启用必要功能：

  WebSettings webSettings = webView.getSettings();
  webSettings.setJavaScriptEnabled(true);
  webSettings.setDomStorageEnabled(true); // Maps API依赖DOM存储
  webSettings.setAllowUniversalAccessFromFileURLs(true); // 本地HTML加载时需开启
  

验证步骤 #

修改后重新打包测试，通过WebView控制台查看网络请求，确认Maps API资源均从maps.googleapis.com和maps.gstatic.com加载，无重定向或拦截情况。

内容的提问来源于stack exchange，提问作者Luis A. Florit