Flutter Web集成google_maps 6.2.0时出现TypeError及渲染断言错误

核心原因 #

错误TypeError: Cannot read properties of undefined (reading 'maps')说明Google Maps JavaScript SDK未正确加载，导致平台视图无法初始化，进而触发后续的断言失败。

具体解决步骤 #

1. 正确引入Google Maps JS SDK #

在web/index.html的<head>标签内添加SDK加载脚本，替换YOUR_API_KEY为你的Google Maps API密钥：

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

注意：该脚本必须放在Flutter主脚本（如main.dart.js）之前加载，保证SDK在Flutter初始化前就绪。

2. 调整渲染模式配置 #

如果使用默认的CanvasKit渲染模式，需添加平台视图支持参数：
在web/index.html的Flutter初始化脚本中，添加extraCommandLineArgs配置：

<script>
  window.addEventListener('load', function(ev) {
    _flutter.loader.loadEntrypoint({
      serviceWorker: {
        serviceWorkerVersion: serviceWorkerVersion,
      },
      onEntrypointLoaded: async function(engineInitializer) {
        let appRunner = await engineInitializer.initializeEngine({
          renderer: "canvaskit",
          extraCommandLineArgs: ['--enable-features=WebPlatformViewEmbedder']
        });
        await appRunner.runApp();
      }
    });
  });
</script>

也可以直接切换到HTML渲染模式快速验证，运行命令时添加参数：

flutter run -d chrome --web-renderer html

3. 规范地图组件初始化逻辑 #

确保在GoogleMap组件初始化完成后再执行相关操作，通过onMapCreated回调确认：

GoogleMap(
  onMapCreated: (controller) {
    // 地图初始化完成后执行后续逻辑
  },
  initialCameraPosition: CameraPosition(
    target: LatLng(37.7749, -122.4194),
    zoom: 12,
  ),
)

4. 校验API密钥权限 #

确认Google Cloud项目已启用Maps JavaScript API，且API密钥无错误限制（如IP范围、API类型限制），保证本地开发IP在允许范围内。

5. 清理缓存重启项目 #

• 清理Flutter缓存：

flutter clean

• 重新获取依赖：

flutter pub get

• 重启Chrome浏览器并重新运行项目，避免缓存导致的SDK加载异常。

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