Android中Map Fragment无法显示地图详情问题求助

问题背景 #

集成Google Map Fragment后，Pixel 3 API 29模拟器及多数测试设备上地图仅显示空白框架，无瓦片/详情内容，仅少数设备正常。项目build.gradle配置如下：

plugins {
    id 'com.android.application'
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

android {
    compileSdk 32

    defaultConfig {
        applicationId "com.G26.fitnessandnutritionbuddy"
        minSdk 23
        targetSdk 32
        versionCode 1
        versionName "1.0"

        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    buildFeatures {
        viewBinding true
    }
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.5.1'
    implementation 'com.google.android.material:material:1.6.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    implementation 'androidx.navigation:navigation-fragment:2.5.2'
    implementation 'androidx.navigation:navigation-ui:2.5.2'
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    implementation 'androidx.annotation:annotation:1.4.0'
    implementation 'androidx.lifecycle:lifecycle-livedata-ktx:2.5.1'
    implementation 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.5.1'
    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    implementation 'com.android.volley:volley:1.2.1'
    implementation 'com.google.android.gms:play-services-location:21.0.0'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.3'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
}

排查与修复步骤 #

1. 核对API密钥配置 #

• 确认secrets.properties中的API密钥有效，且Google Cloud控制台已启用Maps SDK for Android服务
• 检查密钥限制：
  • 包名com.G26.fitnessandnutritionbuddy需与控制台配置完全一致（大小写敏感）
  • 需添加debug和release环境的SHA-1指纹（模拟器使用debug指纹）

2. 升级依赖版本 #

play-services-maps:18.1.0版本较旧，存在兼容性问题，建议升级至最新稳定版，并保持与play-services-location版本匹配：

implementation 'com.google.android.gms:play-services-maps:18.2.0'
implementation 'com.google.android.gms:play-services-location:21.0.1'

3. 完善权限与网络配置 #

• 在AndroidManifest.xml中添加必要权限：

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

• API28+设备需在application标签内添加：

android:usesCleartextTraffic="true"

（或配置网络安全策略允许访问Google Maps域名）

4. 检查设备/模拟器环境 #

• Pixel 3 API29模拟器需确保Google Play Services已安装并更新至最新版本
• 验证设备网络正常，未被代理/防火墙拦截Google Maps请求

5. 确认初始化代码正确性 #

确保Map Fragment初始化逻辑无误：

SupportMapFragment mapFragment = (SupportMapFragment) getChildFragmentManager()
        .findFragmentById(R.id.map);
mapFragment.getMapAsync(googleMap -> {
    // 正常初始化地图属性
});

问题截图 #

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