Flutter Riverpod 在 build 期改 provider 导致整页崩溃，踩坑实录

Flutter Riverpod 在 build 期改 provider 导致整页崩溃踩坑实录作者FungLeo 适用Flutter / Riverpod现象Web 端登录进首页页面一个请求都不发安卓真机却完全正常。前言说实话这个坑折磨了我小半天最后发现根子在一行看起来人畜无害的赋值语句上。事情是这样的项目在安卓真机上跑得好好的进首页刷刷刷全是请求。我顺手在 Chrome 里跑了一下 Web 版登录完进首页——白的转圈都不转Network 面板干干净净一个业务请求都没发出去。我第一反应是跨域第二反应是 Web 端的网络层配置有问题。结果打开控制台一看躺着一条 Riverpod 抛的错关键词是_debugCanModifyProviders。哦豁原来根本不是网络的事儿是页面在构建阶段就已经崩了请求压根没走到发起那一步。这篇就把这个坑完整讲一遍。它有个很讨厌的特点平时不显形一显形就是整页崩溃而且大概率只在 Web 上暴露各位看官要是没见过真挺难往这个方向想。本文要点Riverpod 在build/initState/didChangeDependencies这些构建期方法里同步改 providerdebug 模式会直接抛异常真凶往往是一行写在load()首行的同步state ...再叠加IndexedStack一次性挂载所有子页被放大成整个页面壳子构建崩溃排查突破口看到页面一个请求都不发先查渲染有没有崩别一头扎进网络层CORS / 鉴权 / token修复初始 loading 态在构造器super里一次性给足删掉initState里多余的.notifier.load()安全边界事件回调和await之后随便改构建期同步改会被拦改完全仓搜一遍.notifier.调用点隐患往往不止一处现象只有 Web 崩安卓一切正常先把现象摆清楚方便你对号入座Web 端登录后进首页页面结构渲染不出来或者卡在空白 / 骨架屏首页对应的loadData()没有任何执行痕迹接口一个不发安卓真机、iOS 真机跑同样的代码完全正常控制台能看到 Riverpod 的构建期保护异常_debugCanModifyProviders相关。最迷惑人的就是「安卓正常」这一条。它会把你的注意力全部引到Web 平台适配上去什么 CORS、什么dart:html、什么 Web 端存储不兼容一通乱查——我就是这么浪费掉大半天的。根因Riverpod 不允许你在构建期改 providerRiverpod 有个保护机制在build/initState/didChangeDependencies这些构建期的方法里修改 provider 的状态它会直接抛异常。这个设计本身是合理的。Widget 正在构建的过程中你去改状态就等于告诉框架我刚渲染出来的这一帧已经过期了数据流会变得不可预测所以 Riverpod 干脆在 debug 模式下把这条路堵死。那么我的代码是怎么撞上去的呢两个因素叠加。因素一load()的第一行是同步 setState有一个统计类的 provider写法大概长这样classStatsNotifierextendsStateNotifierStatsState{StatsNotifier():super(constStatsState()){load();// 构造函数里直接调 load}voidload(){statestate.copyWith(isLoading:true);// ❌ 同步就把 state 改了// ... 后面才是 await 请求}}各位看官注意load()的第一行。它在任何await之前就把state改掉了也就是说这行代码是同步执行的。同步意味着什么意味着谁调用load()这次状态修改就发生在谁的执行栈里。如果调用方是initState那这次修改就实实在在发生在构建期。因素二IndexedStack把所有 Tab 一次性挂载了外层的MainShell用的是IndexedStack来做 Tab 切换。IndexedStack有个特性它会一次性构建所有子页面只是把非当前页藏起来不显示而已。这个特性平时是优点切 Tab 不丢状态、不重建但在这里成了放大器// 进首页的那一瞬间4 个 Tab 页的 initState 全都跑了一遍IndexedStack(index:currentIndex,children:const[HomePage(),ItemListPage(),StatsPage(),// 这一页的 initState 里同步调了 .notifier.load()ProfilePage(),],)于是链路就串起来了进入首页MainShell开始构建IndexedStack顺手把 4 个 Tab 全建了其中某个 Tab 的initState同步调用了.notifier.load()load()第一行同步改stateRiverpod 判定你在构建期改 provider抛异常异常发生在MainShell的构建过程中整个壳子构建失败首页的HomePageNotifier.loadData()根本没机会执行表现出来就是——首页不发包。至于为什么只有 Web 暴露构建期保护的触发依赖时序原生端的调度时序相对宽松这一下可能就滑过去了Web 上的时序更脆一撞一个准。所以这类问题在原生端往往是定时炸弹只是还没炸而已不代表你的写法是对的。我是怎么一步步排查的这段弯路我也一并写出来免得各位看官再走一遍。先怀疑跨域。Web 端嘛第一反应就是 CORS。结果 Network 面板里连 OPTIONS 预检都没有——请求根本没发那就跟跨域没关系。再怀疑鉴权状态。以为是 Web 端 token 存取有问题导致提前拦截了。打日志看了一圈token 好好地躺在那儿。发现请求没发这件事本身才是线索。既然一个包都不发那问题就不在网络层而在发请求的那段代码没被执行。方向一下子就转过来了。回头认真读控制台。之前只扫了一眼看到一堆红字就以为是常规 Web 警告。仔细读才发现_debugCanModifyProviders这个关键词Riverpod 明明白白告诉我你在构建期改 provider 了。顺着栈往上找调用方。定位到某个 Tab 页的initState→.notifier.load()→load()首行同步 setState真凶落网。说实话第 3 步是转折点。当你发现请求没发出去的时候就别在网络层耗着了去查渲染和状态流效率高得多。修复把初始 loading 态放到构造器里改法非常简单思路就一句话别在load()里同步改状态初始状态在构造的时候就给足。classStatsNotifierextendsStateNotifierStatsState{// 初始就是 loading 态在 super 里一次性给到不再进 load()StatsNotifier():super(constStatsState(isLoading:true)){load();}Futurevoidload()async{// ❌ 删掉原来首行的同步 state state.copyWith(isLoading: true);finaldataawait_fetch();// 只有在 await 之后才改 statestatestate.copyWith(isLoading:false,data:data);}}为什么这样就好了因为await之后的代码会被丢到下一个微任务里执行那时候当前这一帧的构建早就结束了不在构建期Riverpod 自然不拦。顺手还要做一件事把页面initState里多余的.notifier.load()删掉。// old ❌ 构造器里已经 load 过一次了这里再来一次纯属重复请求overridevoidinitState(){super.initState();ref.read(statsProvider.notifier).load();}// new ✅ 什么都不用写provider 被首次读取时构造器自己会 load改完 Web 端一刷新首页请求唰唰全出来了。OK收工。顺带说说哪些地方改 provider 是安全的既然踩了这个坑就把边界一次性理清楚省得以后写代码提心吊胆。不安全构建期会被拦build()方法体里initState()里同步调用didChangeDependencies()里同步调用任何在上述方法执行栈中同步触发的状态修改。安全事件回调随便改按钮onPressed、onTap之类的用户交互回调onRefresh下拉刷新滚动监听、定时器回调任何await之后的代码。如果你确实需要页面一出来就干点什么又不想改 Notifier 的构造器还有个常规办法是把动作推迟到当前帧渲染完之后overridevoidinitState(){super.initState();// 等这一帧画完再动 provider就不算构建期了WidgetsBinding.instance.addPostFrameCallback((_){ref.read(someProvider.notifier).refresh();});}这个写法能用但我个人更推荐前面那种初始态放构造器的做法——语义更干净也不用额外记一个 API。addPostFrameCallback更适合那种必须等布局完成才能算的逻辑拿它来绕构建期检查多少有点治标不治本的意思哈。另外建议各位看官改完之后全仓搜一遍.notifier.的调用点确认它们都待在事件回调里。这类隐患往往不止一处你只修了报错的那个剩下的还在暗处等着你。小结好啦这个坑就讲到这儿。复盘一下一行写在load()首行的同步state ...加上IndexedStack一次性挂载所有子页的特性两者一叠加就把一个不起眼的写法问题放大成了整个页面壳子构建崩溃。而崩溃又发生在请求发起之前最终伪装成首页不发请求这么一个跟根因八竿子打不着的现象。给各位看官留三条能直接用的结论初始 loading 态用super(const State(isLoading: true))表达别在load()首行同步 setState看到页面不发请求先查渲染有没有崩不要一头扎进网络层IndexedStack是构建期副作用的放大器用它做 Tab 的项目尤其要注意各子页initState里的动作。最后如果这篇文章帮你少熬了一个通宵希望看官您用发财的小手点个小赞哈要是你在 Riverpod 上还踩过别的坑欢迎在评论区聊聊让更多同学少走弯路。谢谢大家本文由 FungLeo 主导Deepseek 优化校阅转发请注明首发地址谢谢大家相关阅读Flutter/Android Release 包连不上网AndroidManifest INTERNET 权限排查实录Flutter dart-define 实现 dev/正式双构建调试代码正式包零残留Flutter 接入 Alice 调试浮窗一个顶层 final 抢跑把 release 网络整没了Flutter Android 构建突发红字一个跟通知无关的库逼你开 core library desugaringFlutter Debug 红屏、Release 灰屏你的 release-only bug只是异常被藏起来了Flutter Material 3 从 0 搭品牌主题系统四件套实战全记录Flutter 把第三方 UI 库渐进迁回 Material 3组件映射总表 四批次替换实战Flutter BrandColors 设计 Token 集中管理消灭硬编码色值实战Flutter 可复用公共组件库设计与落地AppDialog/BottomSheet 等实战