Flutter集成Google Maps无提示崩溃求助

一、AndroidManifest.xml 核心检查点 #

• API Key配置验证：确保API Key的<meta-data>标签放在<application>内部，属性名严格为com.google.android.geo.API_KEY，格式如下：

  <application ...>
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="你的实际API_KEY"/>
    <!-- 其他application内配置 -->
  </application>
  

  注意：不要误写为com.google.android.maps.v2.API_KEY（旧版标识，已废弃）。
• 权限完整性检查：必须添加以下权限到<manifest>标签内：

  <uses-permission android:name="android.permission.INTERNET"/>
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  

  Android 12+ 额外需要添加：

  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  <uses-feature android:name="android.hardware.location.gps" android:required="false"/>
  

• 标签格式校验：检查是否有未闭合的标签、属性拼写错误（比如android:name写成android:names），这类语法错误会导致Manifest解析失败但无明确提示。

二、Dart代码排查 #

• GoogleMap组件初始化：必须指定initialCameraPosition，缺少该参数会直接导致崩溃，示例代码：

  import 'package:google_maps_flutter/google_maps_flutter.dart';
  import 'dart:async';
  
  class MapScreen extends StatefulWidget {
    @override
    _MapScreenState createState() => _MapScreenState();
  }
  
  class _MapScreenState extends State<MapScreen> {
    final Completer<GoogleMapController> _controller = Completer();
  
    static const CameraPosition _kGooglePlex = CameraPosition(
      target: LatLng(37.42796133580664, -122.085749655962),
      zoom: 14.4746,
    );
  
    @override
    Widget build(BuildContext context) {
      return Scaffold(
        body: GoogleMap(
          mapType: MapType.normal,
          initialCameraPosition: _kGooglePlex,
          onMapCreated: (GoogleMapController controller) {
            _controller.complete(controller);
          },
        ),
      );
    }
  }
  

• 权限动态申请：Android 6.0+ 需要动态申请定位权限，未申请权限直接加载地图可能导致崩溃，可使用permission_handler包实现：

  import 'package:permission_handler/permission_handler.dart';
  
  // 在页面初始化时调用
  Future<void> _requestPermissions() async {
    var status = await Permission.location.request();
    if (!status.isGranted) {
      // 处理权限拒绝逻辑
    }
  }
  

三、获取详细错误日志 #

• 查看Logcat：在Android Studio中打开Logcat面板，过滤Error级别日志，查找包含GoogleMap、API_KEY、Manifest关键字的异常信息，比如ApiKeyMissingException（API Key未配置）、SecurityException（API Key权限不足）。
• verbose模式运行：终端执行flutter run -v，查看编译和运行过程中的所有日志，Manifest解析错误通常会在[ ] Merging AndroidManifest.xml段落下出现具体提示。

四、其他关键排查点 #

• API Key有效性：登录Google Cloud Console，确认API Key已启用Maps SDK for Android服务，且应用限制（包名+SHA-1）与当前项目完全匹配。
• 依赖版本兼容：确保pubspec.yaml中google_maps_flutter版本与android/app/build.gradle中com.google.android.gms:play-services-maps版本兼容（可参考官方文档推荐的版本对应关系）。
• 清理缓存重建：执行flutter clean → flutter pub get → flutter run，清除旧的编译缓存。

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