添加自定义启动页后Flutter应用崩溃至锁屏（报错FATAL EXCEPTION）

问题概述 #

添加自定义启动页splash.png到mipmap文件夹、修改styles.xml设置windowBackground后，应用启动崩溃至锁屏，报错FATAL EXCEPTION: wmshell.splashscreen，此前应用运行正常。

排查与解决方案 #

1. 检查图片资源有效性 #

• 确保splash.png已正确放置在所有mipmap分辨率目录（mipmap-mdpi、mipmap-hdpi、mipmap-xhdpi等），各目录下的图片尺寸需匹配对应分辨率规范，避免因尺寸不兼容触发渲染异常。
• 验证图片文件未损坏：替换为一张已知正常的PNG图片测试，排除资源本身问题。

2. 修正styles.xml中的启动主题配置 #

Android 12及以上系统引入了官方SplashScreen API，直接通过windowBackground设置启动页可能与系统splashscreen服务冲突，需调整配置：

<!-- styles.xml 中的 LaunchTheme 配置示例 -->
<style name="LaunchTheme" parent="@android:style/Theme.Material.Light.NoActionBar">
    <!-- 针对Android 12+的SplashScreen配置 -->
    <item name="android:windowSplashScreenAnimatedIcon">@mipmap/splash</item>
    <item name="android:windowSplashScreenBackground">@color/your_splash_background_color</item>
    <!-- 兼容低版本系统 -->
    <item name="android:windowBackground">@drawable/splash_compat</item>
</style>

若仍需使用windowBackground，需引用drawable资源而非直接mipmap，可创建包含splash.png的drawable XML文件（如splash_compat.xml）：

<!-- drawable/splash_compat.xml -->
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@color/your_splash_background_color"/>
    <item>
        <bitmap
            android:src="@mipmap/splash"
            android:gravity="center"/>
    </item>
</layer-list>

3. 确认Manifest与主题的一致性 #

检查AndroidManifest.xml中MainActivity的android:theme="@style/LaunchTheme"引用无拼写错误，且LaunchTheme在styles.xml中已正确定义。

4. 清理项目缓存 #

执行以下命令清理缓存并重建项目，避免旧资源缓存导致的异常：

flutter clean
flutter pub get
flutter run

5. 兼容Flutter嵌入版本 #

当前Manifest中flutterEmbedding值为2，确保使用的Flutter SDK为稳定版，若版本过旧可能存在兼容性问题，建议升级至最新稳定SDK。

附用户提供的AndroidManifest.xml #

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.ogmaproject.ogma">
   <application
        android:label="Ogma"
        android:name="${applicationName}"
        android:icon="@mipmap/launcher_icon">
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:theme="@style/LaunchTheme"
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:hardwareAccelerated="true"
            android:windowSoftInputMode="adjustResize">
            <!-- Specifies an Android theme to apply to this Activity as soon as
                 the Android process has started. This theme is visible to the user
                 while the Flutter UI initializes. After that, this theme continues
                 to determine the Window background behind the Flutter UI. -->
            <meta-data
              android:name="io.flutter.embedding.android.NormalTheme"
              android:resource="@style/NormalTheme"
              />
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>
        <!-- Don't delete the meta-data below.
             This is used by the Flutter tool to generate GeneratedPluginRegistrant.java -->
        <meta-data
            android:name="flutterEmbedding"
            android:value="2" />
    </application>
</manifest>

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