Flutter FutureBuilder未等待Future返回结果问题排查

问题回顾 #

• 最初误以为FutureBuilder没有等待异步函数结果，导致snapshot.data为空
• 调试确认fetchJSON能正常获取到JSON数据，但数据没能正确返回给FutureBuilder
• 最终定位：异步函数内部存在错误的类型转换，且没有抛出明确的报错信息

核心原因 #

FutureBuilder本身确实会等待Future的执行结果，但如果你的fetchJSON函数在解析JSON、转换数据类型时出了错，而且错误被静默处理了（比如没有抛出异常），就会导致Future返回null或者不符合预期的类型，这时候FutureBuilder拿到的snapshot.data自然是空的。因为没有明确报错，才会误以为是FutureBuilder没等待结果。

具体解决步骤 #

1. 给异步函数加异常捕获 #

在fetchJSON里用try-catch包裹解析逻辑，把错误打出来，才能明确问题在哪：

Future<YourDataModel> fetchJSON() async {
  try {
    final response = await http.get(Uri.parse('你的接口地址'));
    if (response.statusCode == 200) {
      // 这里如果类型转换出错，会直接进入catch块
      return YourDataModel.fromJson(json.decode(response.body));
    } else {
      throw Exception('请求失败：${response.statusCode}');
    }
  } catch (e) {
    print('JSON解析/转换错误：$e');
    rethrow; // 把异常抛出去，让FutureBuilder能捕获到
  }
}

2. 在FutureBuilder中处理异常状态 #

别只判断snapshot.hasData，也要加上snapshot.hasError的处理，这样界面上能直接看到错误：

FutureBuilder<YourDataModel>(
  future: fetchJSON(),
  builder: (context, snapshot) {
    if (snapshot.hasError) {
      return Text('加载出错：${snapshot.error}');
    }
    if (snapshot.hasData) {
      // 用正确的数据构建界面
      return YourCustomWidget(data: snapshot.data!);
    }
    // 加载中的默认状态
    return const CircularProgressIndicator();
  },
)

3. 检查类型转换逻辑 #

• 确认YourDataModel.fromJson方法里的每个字段类型，都和JSON返回的字段类型完全匹配（比如JSON返回的是int类型的id，就不能转成String）
• 对于JSON里可能为null的可选字段，要处理null情况，别用强制转换导致静默失败

关键提醒 #

FutureBuilder的工作逻辑没问题，它一定会等Future执行完再更新界面。遇到snapshot.data为空但异步函数能拿到数据的情况，90%以上是异步函数内部在数据处理环节出了静默错误，加异常捕获是最快的排查方法。

内容的提问来源于stack exchange，提问作者Fabrício Carraro