.NET MAUI Android平台离线项目地图加载失败求助

我来帮你排查这个.NET MAUI离线项目中地图瓦片加载失败的问题，结合你提供的配置信息，我整理了几个核心排查方向和对应的解决方案：

1. 离线模式下未配置自定义瓦片源（最可能的核心问题） #

默认情况下，Microsoft.Maui.Controls.Maps 使用的是在线地图瓦片服务（比如Google Maps在线瓦片）。你的项目是离线模式，如果没有配置离线瓦片的来源，地图容器会正常渲染，但无法获取到瓦片资源，最终显示空白。

解决方案： #

你需要为地图添加自定义离线瓦片层，指定本地瓦片文件的路径或者离线瓦片服务器地址。示例代码如下：

后台代码配置（在ContentPage的构造函数或OnAppearing中）：

using Microsoft.Maui.Controls.Maps;

protected override void OnAppearing()
{
    base.OnAppearing();

    // 假设离线瓦片存储在Android的assets/tiles目录下，格式为z/x/y.png
    var offlineTileSource = new UriTileSource
    {
        // 根据你的离线瓦片存储结构调整Uri模板
        UriFormat = "file:///android_asset/tiles/{z}/{x}/{y}.png"
    };

    var offlineTileLayer = new TileLayer(offlineTileSource);
    map.TileLayers.Add(offlineTileLayer);

    // 可选：如果不需要默认的在线瓦片，可以清空默认图层
    // map.TileLayers.Clear();
    // map.TileLayers.Add(offlineTileLayer);
}

注意：需要确保离线瓦片文件已正确打包到Android项目中（比如放在Platforms/Android/assets/tiles目录，并设置文件的生成操作为AndroidAsset）。

2. Google Maps API Key 有效性或绑定信息不匹配 #

虽然你在AndroidManifest.xml中配置了API Key，但以下情况会导致瓦片加载失败：

• API Key 与项目的包名（Application ID）、签名证书SHA-1不匹配（Google Maps Key是严格绑定这两个信息的）
• API Key 已过期或未启用Maps SDK for Android服务
• 离线模式下，Key未配置允许离线访问权限

排查步骤： #

1. 登录Google Cloud Console，检查对应Key的绑定信息：
   • 确认包名和你的项目Platforms/Android/AndroidManifest.xml中的package属性完全一致
   • 确认签名证书的SHA-1值（调试和发布版本的SHA-1可能不同，需分别添加）
2. 检查Key是否启用了Maps SDK for Android服务

3. Android权限缺失或未申请运行时权限 #

即使是离线地图，Android仍需要必要的权限来渲染地图组件：

• 定位权限：ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION（地图控件可能依赖定位权限初始化）
• 存储权限：如果离线瓦片存储在外部存储中，需要READ_EXTERNAL_STORAGE

解决方案： #

1. 在AndroidManifest.xml中添加权限声明：

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<!-- 针对Android 13+的存储权限 -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" android:minSdkVersion="33" />

2. 在代码中申请运行时权限：

// 在ContentPage的构造函数或OnAppearing中
var status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();
if (status != PermissionStatus.Granted)
{
    status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();
}

4. .NET MAUI Maps初始化与配置顺序问题 #

检查MauiProgram.cs中的服务注册顺序，确保UseMauiMaps()在其他配置之前调用，且地图相关服务被正确注册：

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .UseMauiMaps() // 确保这个调用在自定义配置之前
        .ConfigureRmt(new ConfigModel() 
        { 
            AppType = AppType.Offline, 
            ApiType = ApiType.PeaBody 
        });

    // 可选：如果有自定义地图服务，在这里注册
    // builder.Services.AddSingleton<IMapService, OfflineMapService>();

    return builder.Build();
}

5. Google Play Services 兼容性问题 #

• 检查@integer/google_play_services_version是否在项目中正确引用：确保你的Android项目已添加Google Play Services的依赖
• 更新相关NuGet包：确保Microsoft.Maui.Controls.Maps、Microsoft.Maui.Maps的版本与你的.NET MAUI SDK版本完全一致
• 测试设备上的Google Play Services是否为最新版本，旧版本可能导致地图组件初始化失败

最后：通过Logcat定位具体错误 #

以上排查都没解决的话，打开Android Studio的Logcat或Visual Studio的Android日志窗口，搜索以下关键词，获取更精准的错误信息：

• Google Maps
• TileLoader
• API key
• Permission denied

根据日志中的具体错误提示，就能快速定位问题根源。

内容来源于stack exchange