.NET MAUI 启动屏图片不显示且背景色异常
结论
<MauiSplashScreen> 在构建期生效,XAML 运行时不会直接读取它。图片完全不显示、背景色也不对时,建议先检查启动屏资源是否已经正确生成、是否被平台资源覆盖,以及升级 CommunityToolkit.Maui 后是否出现了依赖或缓存问题。可以先做一次彻底清理并重建,然后查看生成后的 Android/iOS 启动屏资源和平台覆盖文件。CommunityToolkit.Maui 通常不直接管理 MauiSplashScreen,但版本升级可能通过依赖、构建任务或缓存影响生成结果;遇到升级后出现异常的情况,可以把它作为排查线索,不要一开始就断定是某个属性失效。
可能原因
- 增量构建或缓存残留:Android 的
res资源、iOS 的 storyboard/launch screen 资源仍是旧版本,导致Color和图片没有更新。 MauiSplashScreen配置未生效:路径、文件名、大小写、重复项或平台覆盖导致资源没有进入最终包。- 平台资源覆盖:Android 的 theme/style/color 或 iOS 的
Info.plist/LaunchScreen 配置覆盖了 MAUI 生成结果。 - 版本兼容性:CommunityToolkit.Maui 15.0.1 与当前 .NET 10/MAUI workload 不匹配,或者升级后构建链出现异常。
- Android 12 及更高版本的系统 SplashScreen 行为:系统会对启动图标做遮罩和尺寸限制;不过 iOS 同时出现异常时,更可能是资源生成或覆盖的问题。
排查步骤
1. 先彻底清理并重建
只点一次 Rebuild 往往不够。删除 bin、obj 后重新还原和构建:
dotnet clean
dotnet restore
dotnet build
如果本机有多个目标框架,分别构建 Android 和 iOS:
dotnet build -f net10.0-android
dotnet build -f net10.0-ios
然后卸载设备上的旧应用再安装,避免系统缓存旧启动屏。
2. 检查 csproj 是否只有一个启动屏项
确认文件真实存在,路径大小写正确,并且没有重复的 MauiSplashScreen,也没有把同一张图又声明成 MauiImage:
<ItemGroup>
<MauiSplashScreen Include="Resources\Splash\splash.png" Color="#262627" />
</ItemGroup>
如果项目里有多个 MauiSplashScreen,先保留一个做最小化测试。文件路径建议使用项目内相对路径,文件名避免空格和特殊字符。
3. 查看生成后的平台资源
构建后到 obj 目录下检查生成的 Android/iOS 启动屏资源,确认:
- 图片资源是否被复制或生成;
- 背景色是否写成了
#262627; - 是否存在旧的
.NET紫色值(例如#512BD4一类主题色)覆盖。
如果生成结果里的颜色仍不是 #262627,应先检查构建配置或平台覆盖,不要先怀疑图片本身。
4. 检查平台覆盖文件
Android 侧重点检查 Platforms/Android/Resources/values 下的 styles.xml、colors.xml 和主题配置,确认没有自定义 windowSplashScreenBackground、启动主题或 Maui.SplashTheme 覆盖生成值。iOS 侧检查 Platforms/iOS/Info.plist 中的 UILaunchStoryboardName,以及项目里是否还存在自定义 LaunchScreen.storyboard。如果自定义启动屏存在,它可能优先于 MauiSplashScreen 的生成结果。
5. 用最小图片做对照测试
临时换一张简单的 PNG,例如纯色或明显图案,放到 Resources\Splash\ 下并更新 Include 路径。这样可以区分“图片本身、尺寸或透明通道问题”和“配置未生效问题”。如果简单图片能显示,再回到原图检查尺寸、透明区域和命名。
6. 验证 CommunityToolkit.Maui 升级影响
如果清理后仍然异常,可以做一次对照:临时把 CommunityToolkit.Maui 固定回 14.2.0,或升级到与当前 .NET 10/MAUI 明确兼容的版本,再清理重建。命令示例:
dotnet add package CommunityToolkit.Maui --version 14.2.0
同时确认 MAUI workload 已更新:
dotnet workload update
如果回退后背景色恢复,说明升级与构建链或依赖有关;如果回退后仍异常,继续按资源覆盖和平台配置排查。
注意事项
MauiSplashScreen的Color是构建期生成配置,改完后必须重新构建,不能只热重载。- Android 12 及以上系统的启动屏由系统 API 控制,图片可能被裁剪或遮罩,不能按普通全屏页面理解。
- 不要同时保留多个启动屏声明;多平台项目中要确认没有条件编译或平台文件夹里的重复资源。
- 如果图片始终不显示,先确保
Resources\Splash\splash.png在最终包内,再讨论尺寸和视觉效果。
备注:内容仅供参考。
