Flutter StreamBuilder拉取Firestore数据无法在屏幕显示

• 实现场景：在ListView内嵌套StreamBuilder异步拉取Firestore好友数据
• 异常表现：页面无内容展示，检查组件mounted状态后调用setState修复无效
• 排查情况：数据拉取逻辑正常，控制台可正常打印获取到的正确数据，但数据始终无法渲染到屏幕上

Widget _showFriends() {
    return Expanded(
      child: StreamBuilder<List<Future<AppUser>>>(
        stream: db.friendStream(),
          builder: (context, snapshot) {
            if(snapshot.hasData) {
              print("in here");
              final friends = snapshot.data!;
              var friend;
              String username = "";
              String firstName = "";
              String photoUrl = "";

              return ListView.builder(
                keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag,
                itemCount: snapshot.data!.length,
                itemBuilder: (context, index) {
                   friends[index].then((value) {
                     friend = value;
                     username = value.username;
                     firstName = value.firstName;
                     //photoUrl = value.photoUrl;
                     print("friend username  -- " + username);
                   });
                  return GestureDetector(
                    onTap: () {
                      Navigator.of(context).push(MaterialPageRoute(builder: (context)
                      => IndividualProfile(
                        sourceType: SourceType.friends,
                        name: friend.firstName,
                        userName: friend.username,
                        aboutMe: friend.aboutMe,
                        photoUrl: friend.photoUrl,
                        individualUid: friend.uid,
                      )
                      ));
                    },
                    child: ListTile(
                      title: Text(username),
                      subtitle: Text(firstName),
                      /*leading: CircleAvatar(
                        backgroundImage: CachedNetworkImageProvider(photoUrl),
                      ),*/
                    ),
                  );
                },
              );
            }
            else if(snapshot.hasError) {
              print(snapshot.error.toString());
              return const Center(
                child: Text("An error occurred please try again later"),
              );
            }
            else {
              return const Center(
                child: CircularProgressIndicator(),
              );
            }
          }
      )
    );
  }

• 异步时序错误：Flutter的build方法是同步执行的，在itemBuilder中调用friends[index].then()注册异步回调时，当前列表项的Widget构建已经同步完成，Text(username)、Text(firstName)使用的是初始定义的空字符串渲染。等Future执行完成触发回调给变量赋值时，不会自动触发当前item的重绘，所以页面始终显示空白。
• 变量作用域错误：把friend、username、firstName这些变量定义在ListView的上层作用域，所有列表项共享这几个变量。就算异步回调触发，变量只会被最后一个执行完成的Future覆盖，最终所有列表项都会显示同一个用户的信息，滑动列表时还会出现内容错乱。
• 空指针风险：点击列表项跳转时读取的friend变量可能还未被异步回调赋值，会直接触发空引用报错。

优先从数据层修改friendStream()的返回类型，直接返回Stream<List<AppUser>>，在数据处理层就完成Future的等待解析，不要把嵌套的异步逻辑丢给UI层处理。
如果暂时无法修改流的返回类型，可以在列表项中使用FutureBuilder单独处理每个用户数据的异步加载，不要在build流程中手动调用then修改变量。修复后的代码示例：

Widget _showFriends() {
    return Expanded(
      child: StreamBuilder<List<Future<AppUser>>>(
        stream: db.friendStream(),
          builder: (context, snapshot) {
            if(snapshot.hasData) {
              final friends = snapshot.data!;

              return ListView.builder(
                keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag,
                itemCount: friends.length,
                itemBuilder: (context, index) {
                  // 用FutureBuilder处理单个好友的异步加载
                  return FutureBuilder<AppUser>(
                    future: friends[index],
                    builder: (context, userSnapshot) {
                      // 单个好友数据未加载完成时显示占位，避免空白
                      if (!userSnapshot.hasData) {
                        return const SizedBox.shrink();
                      }
                      final friend = userSnapshot.data!;
                      return GestureDetector(
                        onTap: () {
                          Navigator.of(context).push(MaterialPageRoute(builder: (context)
                          => IndividualProfile(
                            sourceType: SourceType.friends,
                            name: friend.firstName,
                            userName: friend.username,
                            aboutMe: friend.aboutMe,
                            photoUrl: friend.photoUrl,
                            individualUid: friend.uid,
                          )
                          ));
                        },
                        child: ListTile(
                          title: Text(friend.username),
                          subtitle: Text(friend.firstName),
                          /*leading: CircleAvatar(
                            backgroundImage: CachedNetworkImageProvider(friend.photoUrl),
                          ),*/
                        ),
                      );
                    },
                  );
                },
              );
            }
            else if(snapshot.hasError) {
              print(snapshot.error.toString());
              return const Center(
                child: Text("An error occurred please try again later"),
              );
            }
            else {
              return const Center(
                child: CircularProgressIndicator(),
              );
            }
          }
      )
    );
  }

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