Flutter使用ListView.builder渲染列表报错：Vertical viewport was given unbounded height

核心原因 #

ListView.builder 在垂直方向需要明确的高度约束来确定可滚动区域边界。如果它被嵌套在本身无垂直高度限制的组件（比如 Column、Row 或未设置高度的 Container）中，Flutter 无法计算出 ListView 的可用空间，就会抛出 Vertical viewport was given unbounded height 异常。

具体解决方法 #

1. 用 Expanded 包裹 ListView #

若 ListView 位于 Column 内，通过 Expanded 让它占据父组件的剩余垂直空间：

Column(
  children: [
    // 页面其他组件
    Expanded(
      child: ListView.builder(
        itemCount: jobList.length,
        itemBuilder: (context, index) => JobCard(job: jobList[index]),
      ),
    ),
  ],
)

2. 给 ListView 设置固定高度 #

如果不需要占满剩余空间，用 Container 或 SizedBox 指定固定高度：

Container(
  height: 400, // 根据实际需求调整高度值
  child: ListView.builder(
    itemCount: jobList.length,
    itemBuilder: (context, index) => JobCard(job: jobList[index]),
  ),
)

3. 启用 shrinkWrap: true #

当列表内容总高度可确定时，设置 shrinkWrap: true 让 ListView 根据内容自适应高度（列表项过多时可能影响性能，需谨慎使用）：

ListView.builder(
  shrinkWrap: true,
  physics: NeverScrollableScrollPhysics(), // 无需滚动时可添加此参数
  itemCount: jobList.length,
  itemBuilder: (context, index) => JobCard(job: jobList[index]),
)

4. 用 SingleChildScrollView 包裹父组件 #

若整个页面需要滚动，可将包含 ListView 的父组件（如 Column）放入 SingleChildScrollView，同时禁用 ListView 的滚动能力：

SingleChildScrollView(
  child: Column(
    children: [
      // 页面其他组件
      ListView.builder(
        shrinkWrap: true,
        physics: NeverScrollableScrollPhysics(),
        itemCount: jobList.length,
        itemBuilder: (context, index) => JobCard(job: jobList[index]),
      ),
    ],
  ),
)

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