Flutter安卓设备离线显示白屏及构建失败问题求助

问题现象 #

• 构建阶段：仅当设备联网时才能完成向安卓物理设备的构建，飞行模式下构建失败
• 运行阶段：成功部署后，设备离线时启动应用仅显示白屏，且确认应用启动前未发起任何主动网络请求

Flutter Doctor 检测结果 #

Flutter Doctor results
[✓] Flutter (Channel stable, 3.3.5, on macOS 12.5.1 21G83 darwin-arm, locale en-US)
[✓] Android toolchain - develop for Android devices (Android SDK version 33.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 13.2.1)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2021.1)
[✓] VS Code (version 1.73.1)
[✓] Connected device (1 available)
[✓] HTTP Host Availability

可能原因分析 #

1. 构建阶段的隐性网络依赖 #

• Flutter构建安卓应用时，Gradle可能默认尝试联网检查依赖更新、验证证书或访问Google Maven仓库，飞行模式下这些请求失败直接导致构建中断，即便本地已有缓存。
• 部分第三方Flutter插件在构建过程中需要联网拉取原生依赖或资源，未配置离线缓存策略。

2. 运行阶段白屏的核心诱因 #

• Flutter引擎初始化隐性网络请求：3.3.x版本的Flutter引擎可能在初始化时尝试访问Google服务相关配置、设备兼容性数据，离线时请求超时或失败，导致引擎启动卡住，无法渲染首屏。
• 本地资源加载异常：若应用启动依赖的字体、图片等资源，在打包或引用时存在隐性网络校验逻辑，离线时无法完成校验会导致资源加载失败，最终显示白屏。
• 原生层初始化阻塞：安卓项目的Application类或FlutterActivity初始化逻辑中，可能存在未注意到的网络状态检查或隐性请求，离线时阻塞了Flutter引擎的启动流程。

经验参考与解决方案 #

构建阶段优化 #

• 开启Gradle离线模式：在开发工具（Android Studio/VS Code）中启用Gradle离线模式，强制使用本地缓存的依赖包，避免构建时联网。
• 预缓存依赖资源：执行flutter pub get和./gradlew build --offline命令，预先下载并缓存所有构建所需资源，之后离线构建即可正常完成。

运行阶段排查与修复 #

• 查看引擎启动日志：通过adb logcat -s Flutter抓取启动时的引擎日志，确认是否存在网络相关错误信息。
• 验证本地资源完整性：检查pubspec.yaml中声明的资源是否正确打包到APK，确保所有启动依赖的资源为本地引用，无动态网络加载逻辑。
• 排查原生侧逻辑：检查安卓项目的MainActivity.kt或Application.java，移除不必要的网络状态检查或隐性请求，确保离线时原生初始化流程正常。
• 升级Flutter版本：3.3.x属于较旧稳定版，后续版本大概率修复了引擎初始化的隐性网络依赖问题，升级到最新稳定版后测试离线启动情况。

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