Android Fragment加载Google Maps灰屏无法正常加载问题解决方案

按以下优先级逐一排查修复：

1. 修复基础配置错误 #

• 修正Gradle依赖写法：你当前写的依赖字符串里冒号后存在多余空格，会导致依赖无法正确拉取，替换为正确格式后同步Gradle：

implementation 'com.google.android.gms:play-services-maps:18.0.2'

• 核对AndroidManifest配置：
  • 配置API Key的<meta-data>标签必须放在<application>标签内部，和<application>平级的话系统无法读取到密钥，直接导致鉴权失败。
  • 补充必要权限，在manifest根节点下添加网络相关权限，地图瓦片需要联网加载，缺失权限会直接导致灰屏：

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

  • 核对API Key有效性：密钥需要在Google Cloud控制台绑定对应应用包名、签名文件的SHA1指纹，注意debug和release签名的SHA1值不同，调试阶段必须添加debug.keystore的SHA1，否则鉴权失败。这类问题一般页面底部会显示Google Maps的logo，但地图区域全灰，Logcat会打印Authorization failure相关报错。

2. 修复布局异常 #

你当前布局里第一个子控件是占满全屏的TextView，虽然FrameLayout默认后添加的控件在上层，但这个控件没有实际作用，直接删掉避免层级遮挡或渲染异常，修正后的布局代码：

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsLine">

    <fragment
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

3. 补全地图初始化的空判断 #

当前代码直接强转获取SupportMapFragment实例没有做空校验，当外层Fragment因屏幕旋转、内存回收重建时，会出现实例获取失败、重复添加地图Fragment的问题，修改onCreateView中的初始化逻辑：

@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container,
                         Bundle savedInstanceState) {
    View rootView = inflater.inflate(R.layout.fragment_maps_line, container, false);

    SupportMapFragment mapFragment = (SupportMapFragment) getChildFragmentManager().findFragmentById(R.id.map);
    if (mapFragment != null) {
        mapFragment.getMapAsync(new OnMapReadyCallback() {
            @Override
            public void onMapReady(GoogleMap mMap) {
                mMap.setMapType(GoogleMap.MAP_TYPE_NORMAL);
                mMap.clear();

                CameraPosition googlePlex = CameraPosition.builder()
                        .target(new LatLng(37.4219999,-122.0862462))
                        .zoom(10)
                        .bearing(0)
                        .tilt(45)
                        .build();

                mMap.animateCamera(CameraUpdateFactory.newCameraPosition(googlePlex), 10000, null);

                mMap.addMarker(new MarkerOptions()
                        .position(new LatLng(37.4219999, -122.0862462))
                        .title("Spider Man"));
                mMap.addMarker(new MarkerOptions()
                        .position(new LatLng(37.4629101,-122.2449094))
                        .title("Iron Man")
                        .snippet("His Talent : Plenty of money"));

                mMap.addMarker(new MarkerOptions()
                        .position(new LatLng(37.3092293,-122.1136845))
                        .title("Captain America"));
            }
        });
    }
    return rootView;
}

4. 其他高频问题排查 #

• 如果开启了代码混淆，在混淆规则文件中添加Google Maps相关keep规则，避免核心类被混淆导致加载失败：

-keep class com.google.android.gms.maps.** { *; }
-keep interface com.google.android.gms.maps.** { *; }

• 测试设备必须预装符合版本要求的Google Play服务，国内多数定制系统默认砍掉了GMS服务框架，没有GMS环境Google Maps无法正常运行。
• 运行时过滤Logcat中Google Mapstag的日志，日志会直接打印具体错误原因，比如密钥无效、权限缺失、依赖版本冲突等，对照日志调整效率最高。

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