Flutter应用手机进入睡眠模式后StreamBuilder超时错误如何解决

问题根因 #

该报错和StreamBuilder本身无关，本质是手机进入睡眠模式后，系统为了省电会限制前台应用的网络活动、强制切断闲置时间过长的TCP连接，你的REST API请求对应的Stream收到了连接中断/超时类的错误，才会触发hasError状态。

可行解决方案 #

1. BLoC层添加流错误拦截与自动重试 #

不要让网络层的异常直接下发到UI层，在流的生成逻辑中统一捕获网络相关错误，捕获后自动触发API请求重试，再把最新的正常数据下发到UI。
示例代码：

// 改造前的流逻辑
Stream<DataState> fetchData() async* {
  final res = await customApi.getData();
  yield DataState.success(res);
}

// 改造后的流逻辑
Stream<DataState> fetchData() {
  return Stream.fromFuture(customApi.getData())
    .map((res) => DataState.success(res))
    .handleError((error) {
      // 仅拦截网络异常，业务错误正常下发到UI处理
      if (error is SocketException || error is TimeoutException) {
        // 可自定义重试次数、重试间隔避免频繁请求
        retryFetchData();
      } else {
        throw error;
      }
    });
}

2. 监听应用生命周期，切回前台主动刷新 #

在页面层监听应用生命周期状态，当应用从后台/休眠状态切回前台（生命周期变为resumed）时，主动向BLoC发送刷新事件，拉取最新数据覆盖之前的错误状态。
示例代码：

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  super.didChangeAppLifecycleState(state);
  if (state == AppLifecycleState.resumed) {
    context.read<CustomDataBloc>().add(const CustomDataEvent.refresh());
  }
}

3. UI层添加错误兜底恢复逻辑 #

StreamBuilder的错误分支不要只做报错展示，增加手动重试入口，必要时可添加错误出现后自动重试的逻辑。
示例代码：

StreamBuilder(
  stream: context.watch<CustomDataBloc>().stream,
  builder: (context, snapshot) {
    if (snapshot.hasError) {
      return Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          const Text('数据加载异常'),
          TextButton(
            onPressed: () => context.read<CustomDataBloc>().add(const CustomDataEvent.refresh()),
            child: const Text('点击重试'),
          )
        ],
      );
    }
    // 正常状态的UI渲染逻辑
    return const SizedBox();
  }
)

4. 长连接场景添加心跳保活 #

如果你是用长连接持续接收API推送的数据，需要添加定时心跳机制，每30s-1min发送一次极小的心跳包，避免系统将连接判定为闲置切断。如果心跳检测到连接中断，立刻重建连接拉取全量最新数据。

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