传入mapId启用自定义地图样式时，@/react-google-maps/api渲染异常报错

问题场景 #

原本正常运行的Google Maps组件，在启用自定义地图样式（配置mapId）后出现以下异常：

• 同时配置LoadScript mapIds和地图options的mapId时，抛出错误：

  webgl.js:541 Uncaught (in promise) TypeError: Cannot read properties of null (reading 'indexOf')

• 未配置LoadScript mapIds时，抛出错误：

  webgl.js:234 Uncaught Error: Not initialized.

• 地图多数情况下仅加载标记、无瓦片渲染，偶有正常但始终存在未捕获Promise错误，移除标记后问题依旧。

排查与解决步骤 #

• 严格核对mapId一致性
  确保LoadScript的mapIds数组内的ID，与地图初始化options中的mapId完全匹配，包括大小写、字符长度，避免出现字符多写、漏写或拼写错误。

• 检查Google Cloud端配置

  • 确认项目已启用Maps JavaScript API，且使用的API密钥具备访问该自定义mapId的权限。
  • 确认mapId对应的自定义地图样式已正式发布，未处于草稿、删除或暂停状态。

• 清理缓存并强制刷新

  • 清空浏览器缓存，使用Ctrl+Shift+R（Windows）或Cmd+Shift+R（Mac）强制刷新页面，排除旧资源缓存干扰。
  • 重启本地开发服务，清理构建工具缓存（如React项目的node_modules/.cache目录）。

• 指定Maps API版本降级
  在LoadScript中指定稳定旧版本的API，规避最新版本可能存在的WebGL渲染bug，示例代码：

  <LoadScript
    googleMapsApiKey="你的API密钥"
    mapIds={['你的mapId']}
    version="3.49"
  >
    {/* 你的地图组件代码 */}
  </LoadScript>
  

• 排查WebGL兼容性

  • 在浏览器地址栏输入chrome://gpu/（Chrome）或about:support（Firefox），检查WebGL是否启用、是否存在硬件支持问题。
  • 更换不同浏览器或设备测试，排除设备端WebGL支持异常。

• 简化测试环境
  暂时移除地图组件的额外插件、自定义控件、事件监听等，只保留最基础的初始化代码，验证是否是其他业务代码干扰了mapId的加载流程。

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