.NET MAUI应用中GIF动图仅显示首帧无法播放问题求助

问题说明 #

从Xamarin.Forms迁移至.NET MAUI后，按官方原生GIF加载方案实现时，动图仅渲染第一帧无动画效果，参照公开的已知问题配置Resize=False后问题仍存在。

可落地修复步骤 #

• 修正项目文件（.csproj）的资源配置
  配置顺序错误是该问题最高发的诱因，.NET MAUI的MauiImage规则按代码先后顺序生效，后写的规则会覆盖先写的规则，必须将GIF的特殊配置放在通用图片资源配置之后，且补上缺失的动画启用属性，正确配置示例：

  <!-- 通用图片资源规则，放在前面 -->
  <MauiImage Include="Resources\Images\*" />
  <!-- GIF专属配置，放在通用规则之后才会生效 -->
  <MauiImage Update="Resources\Images\*.gif" Resize="False" IsAnimation="True" />
  

  其中IsAnimation="True"是.NET MAUI GA版本后新增的控制属性，早期已知问题规避方案未提及该配置，缺少该属性时解码逻辑只会提取GIF首帧，不会启动动画帧调度。
• 强制清理项目编译缓存
  配置修改后必须清理旧的编译缓存，否则旧的资源构建结果会被复用，导致配置不生效：
  1. 关闭当前打开的IDE
  2. 手动删除项目根目录下的bin、obj两个文件夹
  3. 重新打开项目执行「重新生成解决方案」操作
• 分平台兼容适配
  • Windows端：如果使用的.NET MAUI SDK版本低于7.0.59，存在GIF动画帧调度的已知bug，直接升级到最新稳定版SDK即可修复
  • Android端：如果项目中自定义了图片渲染Handler，需要确认没有拦截原生IImageSourceService的GIF解码流程，默认原生Handler已支持GIF自动循环播放
  • iOS端：避免给GIF图片设置Aspect="AspectFill"配合父布局裁剪的配置，部分iOS系统版本下该组合会拦截动画帧刷新，替换为AspectFit即可验证是否为该原因导致
• 兜底加载方案
  如果以上配置完成后仍无法正常播放，可以绕过MauiImage的资源编译流程，直接用文件流加载原始GIF文件，示例代码：
  首先在XAML中给Image控件命名：

  <Image x:Name="GifImage" HeightRequest="200" HorizontalOptions="Center" />
  

  然后在页面后台代码的OnAppearing生命周期中加载流：

  protected override async void OnAppearing()
  {
      base.OnAppearing();
      using var gifStream = await FileSystem.OpenAppPackageFileAsync("Resources/Images/giphy.gif");
      GifImage.Source = ImageSource.FromStream(() => gifStream);
  }
  

  该方式直接读取原始GIF文件，不会经过MAUI的图片资源裁剪、压缩流程，可规避所有资源构建阶段的异常。

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