Flutter发布版APK调用API时出现白屏问题求助

1. 检查Release模式网络请求配置 #

• 若API使用HTTP协议：Android 9及以上默认禁止明文网络请求，需创建android/app/src/main/res/xml/network_security_config.xml文件添加配置（仅测试用，正式环境建议切换HTTPS）：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
</network-security-config>

然后在AndroidManifest.xml的<application>标签中引用该配置：

android:networkSecurityConfig="@xml/network_security_config"

2. 完善Bloc异常捕获与状态处理 #

Release模式下Dart错误不会弹窗提示，若API请求异常未被捕获，会导致Bloc无法更新状态，页面停留在初始空白状态：

• 在Bloc的事件处理方法中添加全局异常捕获：

@override
Stream<YourState> mapEventToState(YourEvent event) async* {
  try {
    final response = await http.get(Uri.parse(apiUrl));
    // 处理响应并发射成功状态
    yield YourSuccessState(data: response.body);
  } catch (e, stackTrace) {
    // 发射错误状态，避免页面空白
    yield YourErrorState(message: e.toString());
    // 打印错误日志用于排查
    debugPrint("API请求错误: $e\n$stackTrace");
  }
}

• UI层必须处理所有状态分支，包括初始状态和错误状态：

BlocBuilder<YourBloc, YourState>(
  builder: (context, state) {
    if (state is YourLoadingState) {
      return const CircularProgressIndicator();
    } else if (state is YourSuccessState) {
      return YourContentWidget(data: state.data);
    } else if (state is YourErrorState) {
      return Center(child: Text(state.message));
    }
    // 初始状态显示占位内容，避免空白
    return const Center(child: Text("加载中..."));
  },
)

3. 检查代码混淆规则 #

若开启了代码混淆（android/app/build.gradle中minifyEnabled true），可能导致http或flutter_bloc核心代码被破坏：

• 在android/app/proguard-rules.pro中添加保留规则：

# 保留Flutter核心类
-keep class io.flutter.**  { *; }
-keep class io.flutter.plugins.**  { *; }

# 保留http库相关类
-keep class com.google.gson.** { *; }
-keep class com.google.gson.reflect.TypeToken { *; }

# 保留flutter_bloc相关类
-keep class bloc.** { *; }
-keep class flutter_bloc.** { *; }

• 可暂时关闭混淆（minifyEnabled false）构建APK测试，确认是否是混淆导致的问题。

4. 确保构建正式Release APK #

使用命令明确构建正式版本：

flutter build apk --release

5. 添加请求超时处理 #

时好时坏的情况可能和网络波动有关，给API请求添加超时限制：

final response = await http.get(Uri.parse(apiUrl)).timeout(const Duration(seconds: 10));

[√] Flutter（稳定通道，3.19.5，运行于Microsoft Windows [版本10.0.19045.4170]，区域设置fr-TG）
• Flutter版本3.19.5，位于稳定通道，路径C:\src\flutter
• 上游仓库github.com/flutter/flutter.git
• Framework修订版本300451adae（2周前），2024-03-27 21:54:07 -0500
• Engine修订版本e76c956498
• Dart版本3.3.3
• DevTools版本2.31.1

[√] Windows版本（已安装Windows版本为10或更高版本）

[√] Android工具链 - 开发Android设备（Android SDK版本34.0.0）
• Android SDK路径C:\Users\look\AppData\Local\Android\Sdk
• 平台android-34，build-tools 34.0.0
• ANDROID_HOME = C:\Users\look\AppData\Local\Android\Sdk
• ANDROID_SDK_ROOT = C:\Users\look\AppData\Local\Android\Sdk
• Java二进制文件路径：C:\Program Files\Android\Android Studio\jbr\bin\java
• Java版本OpenJDK Runtime Environment（build 17.0.9+0--11185874）
• 已接受所有Android许可证。

[√] Chrome - 开发Web应用
• Chrome路径C:\Program Files\Google\Chrome\Application\chrome.exe

[√] Visual Studio - 开发Windows应用（Visual Studio Build Tools 2019 16.11.26）
• Visual Studio路径C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools
• Visual Studio Build Tools 2019版本16.11.33529.622
• Windows 10 SDK版本10.0.19041.0

[√] Android Studio（版本2023.2）
• Android Studio路径C:\Program Files\Android\Android Studio
• Flutter插件可从JetBrains插件市场安装
• Dart插件可从JetBrains插件市场安装
• Java版本OpenJDK Runtime Environment（build 17.0.9+0--11185874）

[√] VS Code（版本1.88.0）
• Flutter扩展版本3.86.0

[√] 已连接设备（4台可用）
• TECNO BD2（移动设备）• 063211515C009845 • android-arm    • Android 10（API 29）
• Windows（桌面设备）  • windows          • windows-x64    • Microsoft Windows [版本10.0.19045.4170]
• Chrome（Web）       • chrome           • web-javascript • Google Chrome 123.0.6312.106
• Edge（Web）         • edge             • web-javascript • Microsoft Edge 123.0.2420.81

[√] 网络资源
• 所有预期的网络资源均可用。

• 未发现任何问题！

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