PAYATHON 2026

.NET MAUI 启动屏图片不显示且背景色异常

数据小陈

结论

<MauiSplashScreen> 在构建期生效,XAML 运行时不会直接读取它。图片完全不显示、背景色也不对时,建议先检查启动屏资源是否已经正确生成、是否被平台资源覆盖,以及升级 CommunityToolkit.Maui 后是否出现了依赖或缓存问题。可以先做一次彻底清理并重建,然后查看生成后的 Android/iOS 启动屏资源和平台覆盖文件。CommunityToolkit.Maui 通常不直接管理 MauiSplashScreen,但版本升级可能通过依赖、构建任务或缓存影响生成结果;遇到升级后出现异常的情况,可以把它作为排查线索,不要一开始就断定是某个属性失效。

可能原因

  1. 增量构建或缓存残留:Android 的 res 资源、iOS 的 storyboard/launch screen 资源仍是旧版本,导致 Color 和图片没有更新。
  2. MauiSplashScreen 配置未生效:路径、文件名、大小写、重复项或平台覆盖导致资源没有进入最终包。
  3. 平台资源覆盖:Android 的 theme/style/color 或 iOS 的 Info.plist/LaunchScreen 配置覆盖了 MAUI 生成结果。
  4. 版本兼容性:CommunityToolkit.Maui 15.0.1 与当前 .NET 10/MAUI workload 不匹配,或者升级后构建链出现异常。
  5. 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 在最终包内,再讨论尺寸和视觉效果。

备注:内容仅供参考。