setState 调用了，页面为什么没变化？

按钮点了，日志也打印了，setState 明明执行了，页面却像什么都没发生。

这时先别多调用几次 setState。它只负责通知 Flutter：当前 State 的数据可能变了，请重新执行 build。页面最终显示什么，仍然取决于 build 读到了什么数据。

核心结论：setState 不是“刷新页面”。页面没变化，通常是状态改错了、界面没读取这个状态、更新了错误的组件，或者新状态又被异步结果覆盖了。

先记住它的工作方式

一个界面能更新，需要同时满足三件事：

数据真的发生了变化；
调用的是持有这份数据的 State.setState；
该 State 的 build 使用了变化后的数据。

class _CounterPageState extends State<CounterPage> {
  int _count = 0;
 
  @override
  Widget build(BuildContext context) {
    return TextButton(
      onPressed: () {
        setState(() => _count++);
      },
      child: Text('点击次数：$_count'),
    );
  }
}

这段代码能更新，不是因为 setState 有“强制刷新”能力，而是 _count 改了，并且 build 正在读取它。

原因一：改的不是界面使用的变量

最常见的是同名局部变量遮住了成员变量。

class _OrderPageState extends State<OrderPage> {
  String _status = '等待支付';
 
  Future<void> pay() async {
    await orderRepository.pay();
 
    final _status = '支付成功'; // 错误：新的局部变量
    setState(() {});
  }
 
  @override
  Widget build(BuildContext context) => Text(_status);
}

build 重新执行了，但成员变量 _status 从未改变，所以页面仍显示“等待支付”。

应该修改当前 State 真正持有的数据：

setState(() {
  _status = '支付成功';
});

还有一种情况是数据变了，但经过条件判断、格式化或过滤后，最终文本仍然相同。这也会让人误以为页面没有重建。

原因二：更新了错误的组件

setState 只影响调用它的那个 State，并不是全局刷新按钮。

例如，showDialog 打开的弹窗有自己的构建区域。外层页面调用 setState，不等于弹窗内容会跟着更新。弹窗的临时状态可以交给独立的 StatefulWidget，也可以使用 StatefulBuilder：

var quantity = 1;
 
await showDialog<void>(
  context: context,
  builder: (_) => StatefulBuilder(
    builder: (context, setDialogState) {
      return AlertDialog(
        title: Text('购买数量：$quantity'),
        actions: [
          TextButton(
            onPressed: () => setDialogState(() => quantity++),
            child: const Text('增加'),
          ),
        ],
      );
    },
  ),
);

这里要调用 setDialogState。列表项、底部弹层和拆分后的子组件也是同一个判断：先找到“显示这段内容的 build 属于谁”。

原因三：异步结果把新状态覆盖了

用户先搜索“Flutter”，再搜索“Dart”。如果第一个请求更晚返回，旧结果就可能覆盖新结果。肉眼看起来，像是第二次 setState 没生效。

int _searchVersion = 0;
 
Future<void> search(String keyword) async {
  final requestVersion = ++_searchVersion;
 
  try {
    final result = await searchRepository.search(keyword);
    if (!mounted || requestVersion != _searchVersion) return;
 
    setState(() {
      _items = result;
    });
  } catch (error, stackTrace) {
    logger.error('search failed', error, stackTrace);
  }
}

mounted 判断“页面还在不在”，版本号判断“结果是不是最新的”。两者解决的不是同一个问题。

原因四：把异步操作写进 `setState`

setState 的回调必须同步执行。不要这样写：

setState(() async {
  _profile = await profileRepository.load();
});

正确顺序是先等待结果，再同步提交状态：

final profile = await profileRepository.load();
if (!mounted) return;
 
setState(() {
  _profile = profile;
});

网络异常还应在外层通过 try-catch 处理；连续请求则继续增加取消或版本判断。

一套实用的排查顺序

遇到页面不更新，可以按这个顺序检查：

打印新旧值，确认数据真的变了。
在 build 中临时打印日志，确认它有没有重新执行。
检查 build 是否读取了刚才修改的字段。
检查同名局部变量、错误对象或错误列表项。
确认显示内容的 build 与调用 setState 的 State 是否对应。
检查请求、定时器、订阅或状态管理层是否随后覆盖数据。
异步返回后同时处理生命周期和请求竞态。

先区分“没有重建”和“重建后结果相同”，排查会快很多。

最后记住这几点

setState 申请重新构建当前组件，不是刷新整个页面。
页面是否变化，取决于 build 是否读到了新状态。
父页面、弹窗、列表项和子组件可能属于不同的更新边界。
mounted 只能判断生命周期，不能阻止旧请求覆盖新请求。
不要用更多的 setState 掩盖数据流问题。

问答复盘

Q1：调用 `setState(() {})` 会重新构建吗？

答：当前 State 会申请重新构建，但空回调没有改变任何状态，重建后的界面可能完全相同。

Q2：先修改字段，再调用空的 `setState` 可以吗？

答：通常能触发重建，但不推荐。把状态修改写进回调，更容易看清这次界面变化的原因。

Q3：修改 `List` 内部元素后，必须创建新 `List` 吗？

答：对普通 setState 不是必须；它已经会申请重建。但状态管理框架或选择器可能依赖新引用，需要遵守对应的数据更新协议。

Q4：检查了 `mounted`，为什么请求结果还是错的？

答： mounted 只说明页面仍在组件树中。连续请求还要通过取消、请求标识或版本号防止旧结果覆盖新结果。

Q5：怎么判断是没重建，还是重建后没变化？

答：在 build 中记录一次日志，同时打印它依赖的状态值。build 执行了但值没变，就继续检查变量、状态边界和覆盖逻辑。