如何修复FutureBuilder渲染时出现的Unexpected null value错误

核心报错原因 #

• 语法使用错误：AsyncSnapshot返回的snapshot.data是DocumentSnapshot类型的文档快照对象，并非存储字段的Map，你直接对其按下标取值（如snapshot.data['url']）无法获取到字段值，返回null触发空值报错。必须调用DocumentSnapshot的data()方法才能拿到字段Map。
• 缺少空安全校验：既没有校验文档快照是否存在，也没有对读取的字段做空值兜底，任何一处空值都会触发Unexpected null value报错。
• 布局约束异常：Row组件内部直接嵌套ListView，Row本身无宽度上限，ListView默认会尝试占满最大可用宽度，无界布局约束会导致渲染失败。

修复步骤 #

1. 修正文档字段取值方式 + 补充空校验 #

在FutureBuilder的连接状态判断完成后，新增数据存在性校验，再统一读取字段：

if (snapshot.hasError) {
  return const Center(child: Text('Something Went Wrong'));
}
if (snapshot.connectionState == ConnectionState.waiting) {
  return const Center(child: CircularProgressIndicator());
}
// 新增校验：判断文档是否存在、数据是否为空
if (!snapshot.hasData || !snapshot.data!.exists || snapshot.data!.data() == null) {
  return const Center(child: Text('未查询到对应商家数据'));
}
// 统一把字段转成Map，后续直接从这里取值
final Map<String, dynamic> vendorData = snapshot.data!.data() as Map<String, dynamic>;

2. 替换所有字段取值逻辑，加空值兜底 #

所有原snapshot.data['xxx']的写法全部替换为从vendorData取值，同时给每个字段加默认兜底值，避免空值：

// 图片示例
Image.network(
  vendorData['url'] ?? '', // 空值兜底为空字符串
  fit: BoxFit.cover,
  errorBuilder: (context, error, stackTrace) { // 新增图片加载失败占位
    return const Icon(Icons.broken_image, size: 100);
  },
),
// 文本示例
Text(
  vendorData['name'] ?? '未知商家',
  style: const TextStyle(fontWeight: FontWeight.bold, fontSize: 25),
),
Text(vendorData['dialog'] ?? ''),
Text(vendorData['mobile'] ?? '暂无联系方式'),
Text(vendorData['email'] ?? '暂无邮箱'),
Text(vendorData['address'] ?? '暂无地址'),

3. 修复布局约束问题 #

给Row内部的ListView外层套上Expanded组件，约束ListView的宽度，同时给ListView加shrinkWrap: true避免高度无界：

Row(
  crossAxisAlignment: CrossAxisAlignment.end,
  children: [
    SizedBox(
      height: 100,
      width: 100,
      child: Image.network(
        vendorData['url'] ?? '',
        fit: BoxFit.cover,
        errorBuilder: (context, error, stackTrace) => const Icon(Icons.broken_image, size: 100),
      ),
    ),
    // 新增Expanded约束内部ListView的宽度
    Expanded(
      child: ListView(
        shrinkWrap: true, // 让ListView只占用自身内容需要的高度
        physics: const NeverScrollableScrollPhysics(), // 不需要滚动的话可以禁用滚动
        children: [
          const SizedBox(width: 20,),
          Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text(
                vendorData['name'] ?? '未知商家',
                style: const TextStyle(fontWeight: FontWeight.bold, fontSize: 25),
              ),
              Text(vendorData['dialog'] ?? ''),
            ],
          ),
        ],
      ),
    )
  ],
),

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