Flutter升级3.0.4后Android端splash screen无限显示无法进入主应用

核心问题定位 #

闪屏持续不消失的本质原因是Flutter引擎始终没有完成首帧渲染，原生侧收不到隐藏闪屏的信号，debug和release模式下表现一致。结合给出的代码，有两个高频触发点：

• 代码中仅实例化了根组件App，没有显式调用runApp()挂载组件。Flutter 3.0.4版本收紧了首帧绘制的判定规则，旧版本中可能因时序巧合隐式触发的渲染逻辑在新版本中失效，根组件未挂载时引擎永远不会通知原生侧隐藏闪屏。
• 串行执行的多个异步初始化任务只要有一个抛出未捕获异常、或出现逻辑阻塞一直不返回，后续代码就不会执行，runApp()始终无法触发。

分步修复方案 #

• 补全根组件挂载逻辑，增加初始化阶段异常捕获
  调整mainCommon代码如下，显式调用runApp()挂载根组件，同时给初始化逻辑加异常捕获，避免单个初始化任务失败直接中断整个启动流程：

  void mainCommon() {
    WidgetsFlutterBinding.ensureInitialized();
  
    SentryFlutter.init(
      (options) {
        options.dsn = Config.sentryDsn;
        options.autoAppStart = false;
      },
      appRunner: () async {
        try {
          await Firebase.initializeApp();
          await SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]);
          final GlobalKey<ScaffoldMessengerState> messengerKey = GlobalKey<ScaffoldMessengerState>();
          await BlocOverrides.runZoned(
            () async {
              // 所有初始化完成后必须显式调用runApp挂载根组件
              runApp(
                App(
                  api: Api(Config.grpcChannel),
                  database: await Config.db,
                  appDirectory: await getApplicationDocumentsDirectory(),
                  notificationManager: await NotificationManager.init(Config.grpcChannel),
                  messengerKey: messengerKey,
                ),
              );
            },
            blocObserver: AppBlocObserver(errorCallback: BlocErrorHandler(messengerKey).errorCallback),
          );
        } catch (e, stackTrace) {
          // 捕获初始化阶段的异常，避免异常直接中断流程
          Sentry.captureException(e, stackTrace: stackTrace);
          // 初始化失败时可挂载错误提示页，避免一直停留在闪屏
          runApp(const InitErrorPage());
        }
      },
    );
  }
  

• 定位阻塞的初始化任务
  给每个串行的await初始化任务前后加打印日志，确认是哪个任务卡住了：

  debugPrint("开始初始化Firebase");
  await Firebase.initializeApp();
  debugPrint("Firebase初始化完成");
  // 数据库、文件目录、通知模块初始化都按相同方式加日志
  

  常见的初始化阻塞场景：
  • Firebase谷歌服务配置文件错误、网络受限导致初始化挂起
  • 数据库版本迁移逻辑死循环、存在未释放的数据库锁
  • Android 13+机型上通知权限申请弹窗被阻塞，没有设置授权超时
• 核对本地构建配置
  Flutter 3.0.4默认适配JDK 11，之前手动切换到JDK 8的配置如果和当前Gradle插件版本不匹配，会导致引擎初始化时序异常，可以把Android端的JDK版本切回11再试；同时检查MainActivity代码，删除自定义的旧闪屏控制逻辑，避免和系统闪屏、flutter_native_splash的逻辑冲突。
• 清理构建缓存后重新编译
  回退版本、修改配置后执行以下命令清理缓存，避免旧构建产物干扰结果：

  flutter clean
  cd android && ./gradlew clean
  cd .. && flutter pub get
  

  再重新运行应用即可。

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