企业官网建设流程全解析

维基百科阅读器这个系列写到现在，终于轮到状态管理了。前面七篇把环境配置、工程骨架、网络层封装、首页列表、详情页渲染、搜索交互和路由跳转都跑通了，项目长成了“能用”的样子。但用过几轮你就会发现，光靠setState和构造函数传参撑起来的 App，一旦功能叠加起来就是灾难：搜索框的 loading 状态分散在页面里、详情页报错后没法统一重试、收藏了哪篇文章翻个页面就忘了、右上角切换语言后每个页面都要手动刷新。这些症状指向同一个问题——状态没有体系。

这篇我就按这个真实项目的需求，把 Flutter 里的状态管理从选型到落地完整讲一遍，重点讲三件事：状态怎么按业务拆，Cubit/Bloc 这套方案具体怎么写，以及跨页面共享状态时容易踩的坑。代码我会贴关键片段，每段都会解释为什么这么写。适合手里已经有一个能跑的 Flutter 项目、准备把状态管理正式纳入工程体系的开发者。

1. 项目现状与状态管理选型思路

1.1 前七篇的工程进展回顾

先花点时间对齐一下项目进度。第 1 到第 3 篇是地基：环境搭建、工程骨架、Dio 封装和数据模型。页面能打开，数据能拉到，但要人肉拼Text。第 4 到第 7 篇把首页列表、详情页渲染、搜索交互和路由导航补齐，到现在，项目文件长这样：

lib/ main.dart core/ api/ wiki_api.dart models/ article.dart search_result.dart screens/ home/home_screen.dart search/search_screen.dart detail/article_detail_screen.dart favorites/favorites_screen.dart widgets/ article_card.dart loading_view.dart error_view.dart

问题很明确：SearchScreen自己用StatefulWidget管关键词和结果列表，详情页用FutureBuilder硬扛加载状态，收藏页直接维护了一个内存List。这些状态互相不通，切页就丢。收藏一篇百科词条，回到首页再进来，刚才收藏的东西没了，因为FavoritesScreen每次 build 都重新List.empty()。

这一篇的目标，就是把散落在各个StatefulWidget里的状态收编成体系，让页面只负责“消费状态”，而不是“生产状态”。说白了，UI 从LocalState驱动改成Cubit/Bloc驱动之后，所有按钮回调、网络请求、页面刷新都变成了统一格式：发起动作 → 发状态变更 → UI 响应。

1.2 维基百科阅读器到底需要管哪些状态

动手写代码之前，我得先拉一张状态清单。不是所有状态都值得建 Cubit，也不是所有状态都适合全局共享。维基阅读器这种内容型 App，状态大致分五类：

这里的核心区分是“瞬时状态”和“持久状态”。搜索关键词是瞬时的，用户搜完关掉页面，这个关键词没有保留价值；收藏列表是持久的，杀掉 App 再打开，不该丢。瞬时的用页面级 Cubit，持久的用全局单例外加HydratedBloc自动落盘。

还有一类容易被忽略的状态是“UI 控制的副作用”：比如收藏成功后要不要弹 SnackBar、详情加载失败后要不要提示重试按钮。这些不放状态类里，而是靠BlocListener监听状态变化，统一处理，避免 UI 里塞一堆if (state.isFail) showDialog(...)。

1.3 为什么选 Bloc/Cubit 而不是 Provider/Riverpod/GetX

我知道每次聊方案选型都容易吵起来，所以我先把结论放这：这套项目用的是 flutter_bloc 家族，策略是"Cubit 优先，真正需要事件驱动时再上 Bloc"，再配合 HydratedBloc 做持久化。原因有三条。

第一，状态机表达清晰。阅读器的搜索场景就是“输入词→加载中→成功/失败”，详情就是“请求→加载中→成功/失败”。用 Cubit 的emit表达状态流转，天然是一棵有限状态机，不存在isLoading && isError同时为 true 的非法状态。这比在页面里维护两个 bool 靠谱得多，我最早给详情页写的版本就是_loading和_error两个 bool，结果有一次 404 的时候两个都成了 true，页面直接空白。

第二，可测试性。Cubit 不依赖BuildContext，测试的时候SearchCubit(api: mockApi)直接 new 出来，调用onQueryChanged('flutter')，然后断言状态序列即可。不需要起 Widget 测试环境，也不需要 pumpWidget。对内容型项目来说，网络层和状态层的测试价值最高，UI 层反而不用测太细。

第三，HydratedBloc 是现成的持久化方案。收藏和历史这种需要跨会话保留的状态，把 Cubit 换成HydratedCubit，再实现fromJson/toJson两个方法，写入和恢复就自动完成了。省掉手写 SharedPreferences 读写那一堆模板代码。

为什么不直接用完整 Bloc 的Event + State模式？维基阅读器的大多数交互还是“一个动作对应一个状态变更”，没有复杂的用户操作序列，比如“连点五次某个按钮才触发一个动作”。这种情况用 Event 层就是纯模板代码，一个方法调用和一个mapEventToState分支是重复劳动。Cubit 直接把方法变成事件入口，代码量少一层，心智负担也低。

为什么不选 Riverpod 或 GetX？不是它们不行，而是对中小型团队而言，Bloc 这套模式有一个很实际的优点：约定感强。页面里一眼能看到BlocProvider挂在哪个节点、BlocBuilder监听哪个状态、context.read触发什么动作，新人接手代码时不需要纠结依赖注入的定义位置。

2. 核心状态模块设计与拆分

2.1 搜索模块的状态机设计

搜索是阅读器里交互最强、状态最多的模块，我拿它当第一个拆分案例。先看状态类，我用freezed把状态定义成 sealed 类，核心代码长这样：

import 'package:freezed_annotation/freezed_annotation.dart'; part 'search_state.freezed.dart'; @freezed abstract class SearchState with _$SearchState { const factory SearchState.initial() = SearchInitial; const factory SearchState.loading({required String keyword}) = SearchLoading; const factory SearchState.success({ required String keyword, required List<SearchResult> results, }) = SearchSuccess; const factory SearchState.empty({required String keyword}) = SearchEmpty; const factory SearchState.failure({ required String keyword, required String message, }) = SearchFailure; }

状态机的流转是：initial→ 用户输入非空关键词 →loading→ 请求成功且结果非空 →success；请求成功但结果为空 →empty；请求异常 →failure。failure状态下用户换个关键词，又回到loading，再走一遍。

为什么不用bool isLoading, bool isError, String keyword拼？因为组合爆炸。真踩过坑的人知道，一旦加了“加载更多”分页逻辑，就要有isFirstLoading、isRefreshing、isLoadMore三个标志位，四个 UI 状态需要的布尔组合是 2 的 3 次方，其中有意义的状态可能只有五个，剩下全是非法组合。而 sealed class 的好处是，每个状态都是独立类型，switch (state)里漏了分支编译器直接报错，想拼出非法状态都没机会。

搜索还有一个容易忽略的细节：防抖。用户连续输入“flutter”这个词，会触发 f、fl、flu、flut……六次请求，服务端压力小问题不大，但每次请求回来都emit(loading)，页面列表会反复闪加载态。所以onQueryChanged里要挂一个短Timer，400 毫秒内没有新输入才真正发起请求。这个 400ms 是我调过几版之后的折中值：太短防不住快速输入，太长用户会明显感觉搜索响应迟钝。

2.2 文章详情的加载状态与异常流转

详情页比搜索简单，但它有一个特殊价值：展示“页面级 Cubit”和“全局 Cubit”如何协作。详情请求的是单篇完整页面内容，不需要全局缓存，所以用页面级 Cubit，跟着页面走，页面销毁状态就释放，省内存。

@freezed abstract class ArticleDetailState with _$ArticleDetailState { const factory ArticleDetailState.initial() = ArticleDetailInitial; const factory ArticleDetailState.loading() = ArticleDetailLoading; const factory ArticleDetailState.success({required ArticlePage page}) = ArticleDetailSuccess; const factory ArticleDetailState.failure({ required String title, required String message, }) = ArticleDetailFailure; }

加载成功的回调里除了emit(ArticleDetailState.success(page))，还要顺手做一件事：把当前词条写入全局的HistoryCubit。这里我故意把“页面状态更新”和“全局状态更新”放在同一个方法里，是因为阅读历史必须以“详情页真的加载成功”为前提。很多新手会在ArticleDetailScreen的initState里立刻historyCubit.add(title)，结果页面还没加载成功、用户根本没看到内容，历史里就有了，这是错的。让数据有效性决定全局状态的行为，这也是状态管理“单一数据源”思想的一部分。

retry()方法也要讲清楚：失败状态下，用户点重试按钮，实际是重复执行load(title)。因为ArticleDetailCubit是同一个实例，重试时先emit(loading)再重新请求，UI 自动切回加载动画。这里面有一个经验：重试不要新建 Cubit。很多人图省事在ErrorView里直接context.read<ArticleDetailCubit>().load(title)，这个思路是对的；但如果你为了“重置状态”而把页面整体setState重建，Cubit 实例就换了，监听关系断裂，容易出问题。

2.3 收藏与历史的状态持久化

收藏和历史这两个模块，代码结构高度相似，都是HydratedCubit<State>，区别只在数据来源和排序规则。收藏我设成：新收藏的排前面，取消收藏就从集合里移除。历史则是按时间倒序，同一篇文章重复打开时，把它挪到最前。

持久化这块要强调一个容易踩的坑：用HydratedBloc前必须先初始化存储。很多人的代码写成这样：

void main() { runApp(const WikiReaderApp()); }

然后一运行就报Null check operator used on a null value，一脸懵。这是因为HydratedBloc.storage默认是 null，必须先在main里给全局存储赋值：

void main() async { WidgetsFlutterBinding.ensureInitialized(); final storage = await HydratedStorage.build( storageDirectory: await getApplicationDocumentsDirectory(), ); HydratedBloc.storage = storage; runApp(const WikiReaderApp()); }

HydratedCubit的原理其实很朴素：它监听状态变化，把toJson(state)的结果写到本地文件；App 启动时读文件，调用fromJson(json)恢复状态。两个方法返回 null 就表示“没有可恢复数据”，Cubit 保持初始状态。对收藏数据来说，toJson就是把List<Article>序列化成一堆 Map，fromJson反过来。

这里还要插一句：不要为了持久化把所有 Cubit 都换成 HydratedCubit。搜索关键词、详情内容这些瞬时状态，写进本地文件纯属浪费磁盘和启动时间。判断标准就一条：杀掉 App 之后，这个状态还有没有价值。

2.4 跨页面共享与 Navigation 状态保持

“Flutter Navigator 切换页面后，会丢失状态吗？”这个问题的答案不是简单的会或不会，而是取决于你的状态实例挂在哪个节点。Cubit/Bloc 实例的存活周期由BlocProvider的位置决定：挂在MaterialApp之上的，整个 App 生命周期内都存在；挂在某个页面内的，页面从导航栈弹出时，Element 树销毁，Cubit 跟着走dispose。

我见过不少项目在HomeScreen里建了一个FavoriteCubit，然后通过构造函数传给FavoritesScreen。从 Home push 过去时数据还在，但切到别的 Tab 再回来，Home 被销毁过一次，Cubit 没了，收藏页跟着崩。这不是 Flutter 的锅，是实例位置设计错了。

正确的做法分两种情况：

• 全局共享状态：在MultiBlocProvider里统一创建，挂在MaterialApp外层。
• 跨页面传递局部状态：比如从列表页点进详情页，想复用同一个搜索 Cubit，用BlocProvider.value传入已有实例。

BlocProvider.value( value: context.read<SearchCubit>(), child: const ArticleDetailScreen(), )

但这里有个限制：value里的实例生命周期必须比新页面长。如果这个 Cubit 本来就挂在列表页的BlocProvider(create: ...)里，push 详情页时还没销毁，可以用；如果列表页马上就要被替换掉，那新页面拿到的是一个即将被 dispose 的对象，一调用就报错。保险的做法是把这种需要跨页复用的 Cubit 上移到公共父级。

另外有一类坑跟 Flutter 自带的PageStorage有关。用了PageStorageKey之后，页面滚动位置会被系统缓存，但如果你复用了同一个 key（比如列表项里的子组件都用了相同的PageStorageKey('item')），状态恢复时会串位。排查这类问题的方法很简单：把 key 换成唯一值，或者干脆去掉，看滚动位置是否恢复正常。状态管理方案不是万能药，及时区分“Cubit 状态”和“Flutter 组件自身状态”能省很多调试时间。

3. 实操：状态管理代码落地

3.1 依赖配置与工程目录调整

先把pubspec.yaml里和状态管理相关的依赖列出来：

dependencies: flutter: sdk: flutter dio: ^5.4.0 equatable: ^2.0.5 flutter_bloc: ^8.1.5 hydrated_bloc: ^9.1.4 path_provider: ^2.1.2 freezed_annotation: ^2.4.1 dev_dependencies: build_runner: ^2.4.8 freezed: ^2.4.6

版本号按你项目实际情况锁定，别直接抄，flutter 版本不一样依赖解析结果会有差异。

工程目录我建议改成按 feature 纵切，而不是继续往screens里堆文件：

lib/ core/ api/ models/ features/ search/ search_cubit.dart search_state.dart search_screen.dart article/ article_detail_cubit.dart article_detail_state.dart article_detail_screen.dart favorites/ favorite_cubit.dart favorite_state.dart favorites_screen.dart history/ history_cubit.dart history_state.dart

同一个 feature 的 Cubit、State、Screen 放一起，改代码时不用在screens、blocs、states三个目录来回跳。之前和一个团队协作时他们用“类型先行”的目录，blocs文件夹里几十个文件，找某个业务逻辑像大海捞针，后来全部改成 feature 纵切，效率明显提升。

这里顺带提一下热词里出现的 “Flutter 中 part”。search_state.dart里第一行part 'search_state.freezed.dart';，它的作用是让 freezed 生成的代码和你的手写代码属于同一个 library，共享私有类型和导入关系。这不是代码拆分工具，而是“一个库由多个文件组成”的语法。很多新手试图用part把一个大文件拆成小文件，然后发现子文件的变量不能直接调用，满脸疑惑。记住一条：part只应该用于代码生成器（freezed、json_serializable）的产物，手动管理业务代码不要依赖它。

3.2 SearchCubit 实现与防抖处理

SearchCubit完整代码，配合注释解释关键点：

class SearchCubit extends Cubit<SearchState> { SearchCubit({required WikiApi api}) : super(const SearchState.initial()); final WikiApi _api; Timer? _debounce; void onQueryChanged(String keyword) { _debounce?.cancel(); final text = keyword.trim(); if (text.isEmpty) { emit(const SearchState.initial()); return; } emit(SearchState.loading(keyword: text)); _debounce = Timer(const Duration(milliseconds: 400), () async { try { final results = await _api.search(text); if (results.isEmpty) { emit(SearchState.empty(keyword: text)); } else { emit(SearchState.success(keyword: text, results: results)); } } catch (e) { emit(SearchState.failure(keyword: text, message: e.toString())); } }); } @override Future<void> close() { _debounce?.cancel(); return super.close(); } }

逐段拆解。onQueryChanged是 UI 层 TextField 每次输入变化时调用的方法，第一件事就是取消上一次的Timer，这是防抖的核心：只要用户在 400ms 内继续输入，前面的请求就不会发出。trim()之后再判断空字符串，是为了处理用户只输入空格的情况，避免发一个空关键词给后端。

emit(SearchState.loading(...))放在 Timer 外面而不是Timer回调里，是为了让 UI 第一时间反馈“正在搜索”。如果你把 loading 放在回调里，用户输完字要等 400ms 才看到加载转圈，体验会变得很迟钝。这个顺序我是调过好几次才确定的：先显示 loading，再进入防抖等待期，最后真正发请求。

close()里取消 Timer 是防泄漏的关键。页面退出后 Cubit 会被 dispose，如果没有取消_debounce，Timer 回调仍然可能执行，然后调用emit修改一个已经不存在的状态，轻则报错，重则崩溃。这个问题在 Widget 测试里尤其明显，跑完测试一检查unhandled exception，十有八九是 Timer 没清理。

3.3 详情状态机与 UI 联动

详情 Cubit 里最值得讲的是它和HistoryCubit的协作：

class ArticleDetailCubit extends Cubit<ArticleDetailState> { ArticleDetailCubit({ required WikiApi api, required HistoryCubit historyCubit, }) : _api = api, _history = historyCubit, super(const ArticleDetailState.initial()); final WikiApi _api; final HistoryCubit _history; Future<void> load(String title) async { emit(const ArticleDetailState.loading()); try { final page = await _api.fetchPage(title); emit(ArticleDetailState.success(page: page)); _history.add(page); } catch (e) { emit(ArticleDetailState.failure(title: title, message: e.toString())); } } void retry() { final current = state; if (current is ArticleDetailFailure) { load(current.title); } } }

load成功后再调_history.add(page)，这是刻意保持了顺序。ArticleDetailCubit通过构造函数接收HistoryCubit的引用，而不是直接context.read<HistoryCubit>()，因为 Cubit 不感知 BuildContext。依赖注入时机放在了BlocProvider创建时：

BlocProvider( create: (context) => ArticleDetailCubit( api: context.read<WikiApi>(), historyCubit: context.read<HistoryCubit>(), ), )

这种方法叫构造器注入，好处是测试时不用起整个 Widget 树，直接两个 Cubit 对象拼起来测。

UI 组件用BlocConsumer同时监听 builder 和 listener：

BlocConsumer<ArticleDetailCubit, ArticleDetailState>( builder: (context, state) { return switch (state) { ArticleDetailLoading() => const LoadingView(), ArticleDetailSuccess(:final page) => ArticleContent(page: page), ArticleDetailFailure(:final message) => ErrorView(message: message), _ => const SizedBox.shrink(), }; }, listener: (context, state) { if (state is ArticleDetailFailure && state.message.contains('404')) { ScaffoldMessenger.of(context).showSnackBar( const SnackBar(content: Text('这个词条在百科里不存在')), ); } }, )

builder里用 Dart 3 的 switch 表达式，每个状态对应一个 Widget，状态枚举完整性由编译器保证。listener只在状态变更时触发，适合放 SnackBar、导航、弹窗这类有副作用（side-effect）的操作。为什么不能把 SnackBar 放 builder 里？因为 builder 可能因为父级 rebuild 被多次调用，同一条提示会被弹好多次。BlocListener只监听“状态实例变化”这一次，天然避开了重复问题。

3.4 HydratedBloc 持久化收藏与历史

收藏模块的代码，重点看fromJson/toJson的实现：

class FavoriteCubit extends HydratedCubit<FavoriteState> { FavoriteCubit() : super(const FavoriteState(items: [])); void toggle(Article article) { final items = state.items; if (items.any((e) => e.id == article.id)) { emit(FavoriteState(items: items.where((e) => e.id != article.id).toList())); } else { emit(FavoriteState(items: [article, ...items])); } } bool isFavorite(String id) => state.items.any((e) => e.id == id); @override FavoriteState fromJson(Map<String, dynamic> json) { return FavoriteState( items: (json['items'] as List) .map((e) => Article.fromJson(e as Map<String, dynamic>)) .toList(), ); } @override Map<String, dynamic> toJson(FavoriteState state) { return {'items': state.items.map((e) => e.toJson()).toList()}; } }

toggle方法里我用state.items做快照，再基于快照生成新集合。Bloc 家族有个铁律：永远不要修改 state 里的对象，而是生成新对象再 emit。如果你直接state.items.add(article)然后emit(state)，状态类的==判断可能发现“内容没变”，UI 不刷新，因为对象引用没变。这个坑在新手里出现频率极高，我见过一个老项目里几乎所有 Cubit 都踩了一遍，全场排查了半天才发现 flatted state 没有做copyWith重建。

为什么收藏模块用HydratedCubit，而搜索不用？我再说一遍判断标准：收藏列表是用户数据资产，App 杀掉重开不能丢；搜索关键词是临时交互状态，丢了无感。这也是main.dart里HydratedBloc.storage必须在runApp前初始化的原因——如果 storage 没配置好，任何HydratedCubit在第一次emit落盘时都会报错。

另外提醒一点：Article的toJson/fromJson要两个都有，不然序列化不对称，写进去的数据读不出来。测试对称性最简单的方法：写完toggle后打个断点看toJson输出，再杀掉 App 冷启动看fromJson恢复的数据条数是否一致。

4. 实战踩坑：从状态管理到构建链路

4.1 TabBar 与 Navigator 的状态丢失排查

先回答热词里的那个经典问题：“Flutter Navigator 切换页面后，会丢失状态吗？”准确说法是：会丢，而且丢的往往是你没放进状态管理里的状态。导航切换本身不销毁 Cubit，只要实例是挂在导航栈外层的。但如果页面用了BlocProvider(create: ...)在自身创建，push 走后页面虽然没立即销毁（还在下层栈里），Cubit 的销毁实际发生在dispose时，也就是页面从栈里弹出时。所以很多人的现象是：Navigator.push到详情页再返回，列表状态还在；但Navigator.pushReplacement之后，原页面被替换，Cubit 就销毁了，返回后新页面直接白屏。

排查方法很简单：在 Cubit 的close()里打印日志，看它什么时候被销毁。如果发现页面一隐藏就销毁，说明 Cubit 的BlocProvider位置在页面内部。这就是为什么我在第 2 章反复强调，需要跨页共享的状态必须上移到公共父节点。

TabBar 里也藏着一个状态坑。阅读器首页分了“推荐”“收藏”“历史”三个 Tab，我用TabBarView承载。起初直接在 Tab 里堆FavoriteCubit的监听，结果来回切换 Tab 时，列表状态总是丢失。最后定位到原因：TabBarView默认会销毁不可见 Tab 的子 Widget，对应的BlocListener也没了。解法是在TabBarView外面包IndexedStack，让三个 Tab 常驻内存，状态自然就不丢：

IndexedStack( index: _tabIndex, children: const [ HomeScreen(), FavoriteScreen(), HistoryScreen(), ], )

代价是三个页面同时存活，内存稍微多占一点，但对内容型 App 完全可接受。另外关于“TabBar 点击取消动画效果”，网上问的人很多。两个层面处理：禁止用户左右滑动切 Tab，给TabBarView设physics: NeverScrollableScrollPhysics()；点击 TabBar 自带的切换动画如果嫌慢，把TabController的animateTo时长改成Duration.zero：

_tabController.animateTo(index, duration: Duration.zero, curve: Curves.easeOut);

4.2 EventChannel 与原生交互的通道状态

维基阅读器做到后面会遇到一个需求：点击词条里的某个特殊资源，需要跳原生 Activity 播放视频；或者原生侧在后台做一些耗时解析，把进度推回 Flutter。这是典型的混合开发场景，状态管理也要横跨 Flutter 和原生。

MethodChannel用于 Flutter 主动调原生，属于“一问一答”，适合跳页面、传参数。EventChannel用于原生主动推事件给 Flutter，属于“订阅流”，适合进度推送。我实际项目里的做法是，在 Cubit 内部维护 EventChannel 的订阅，用StreamSubscription接收原生事件，然后emit对应的状态：

class NativeTaskCubit extends Cubit<NativeTaskState> { NativeTaskCubit({required this.channel}) : super(const NativeTaskState.idle()) { _sub = channel.receiveBroadcastStream().listen((event) { emit(NativeTaskState.progress(event['percent'] as int)); }); } final EventChannel channel; late final StreamSubscription<dynamic> _sub; @override Future<void> close() async { await _sub.cancel(); await super.close(); } }

这里最容易犯的错误是忘记在close里 cancel 原生事件订阅。Flutter 侧页面销毁后，如果 EventChannel 的订阅还活着，原生的回调会打到已经被 dispose 的 Cubit 上，轻则掉事件，重则内存泄漏或直接异常。写法的关键点是：Cubit 持有订阅，而不是页面持有订阅，这样关闭页面时状态对象会自动清理通道。

如果整个阅读器是以混合工程形式嵌在 Android 原生 App 里，局面会更复杂一点。可以把 Flutter 模块作为独立引擎启动，只通过MethodChannel暴露几个入口方法（打开首页、打开指定词条），原生将这些方法映射到Navigator跳转。此时 Flutter 侧的状态管理全部由自己内部接管，原生只负责“入口”和“回传事件”，不要试图在原生侧直接读 Flutter 的 Cubit 状态，分层边界一旦打破，后续维护成本会成倍上涨。

4.3 打包构建链路的问题速查

状态管理代码写完之后，很多人会卡在打包构建这一步，热词里也能看到一堆相关的报错记录。我把这段时间自己遇到和帮人解决的问题整理成速查表，照顺序排查即可。

第一行的报错很典型。新工程模板默认已经用 plugin DSL，老工程迁移时会遇到这个提示。改法是打开android/settings.gradle，在pluginManagement的plugins块里加id "com.flutter.gradle-plugin"，然后在android/app/build.gradle删掉apply plugin: 'com.android.application'和 Flutter 相关的 apply 语句。如果项目还有自己写的 Gradle 插件，注意兼容性。

第二行“SDK 版本不被完全支持”见过好多次。原因是 Flutter 版本迭代太快，某些大版本升级后，老项目里environment: sdk: '>=3.0.0 <4.0.0'的约束会解析到不兼容的版本。处理方式：先看官方稳定版号，再把pubspec.yaml的environment改成<4.0.0之类的宽泛约束，然后flutter pub upgrade。

第三行那个could not close input stream类错误，属于典型的缓存问题。每次 CI 构建失败，我第一反应就是flutter clean，然后删android/.gradle，几乎解决 80% 的问题。如果还不行，再去查有没有自定义的 proguard 或资源混淆脚本，那才是真正的元凶。

4.4 状态管理中的代码组织细节

最后聊一点代码组织层面的细节，这对一个系列项目的长期维护很重要。

第一个是part关键字和代码生成。freezed生成的文件必须用part引入，这是语法要求，我自己用build_runner build --delete-conflicting-outputs生成之后，会把生成的文件一起提交到仓库里，团队其他人 clone 下来不需要跑生成命令就能直接用。有团队喜欢用pub run build_runner build每次改完模型跑一遍，我觉得小项目没必要，生成物提交一次省事很多。唯一的坑是：合并代码时如果两个人同时改了同一个search_state.dart，生成文件冲突，解决冲突时注意重新跑一次构建命令。

第二个是命名习惯。Cubit 文件名带不带_cubit后缀不重要，重要的是Cubit 和它的 State 必须放在同一个目录。我见过有人把 state 放models/，cubit 放blocs/，结果改一个字段要跨目录改三个文件，非常痛苦。

第三个是context.read和context.watch的使用准则。在onPressed回调里用context.read<SearchCubit>()触发方法，这是合理的；在build方法里用context.read读取状态值放到局部变量，大多数情况下是问题不大，但如果你把它写在需要更新 UI 的地方，它会读一次值就不再更新。普通context.watch只监听第一个找到的 Provider，如果你在MultiBlocProvider里 watch 的 Cubit 不是你想监听的那个，UI 会静默不刷新。排查方法很简单：确认你 watch 的 Cubit 在 Provider 树上的层级高于当前 Widget。

第四个是关于 “对话状态管理”这个词，我自己的理解是“用户每次操作和系统响应构成一段对话”。Cubit 最顺手的一点就是它天然支持这种对话：方法入口是“用户说了什么”，emit是“系统回答了什么”，UI 是“对话内容的展示层”。写代码时保持这个心智模型，不容易出现“状态改了但 UI 不响应”的问题。

写在最后的实操体会

我实际做这个项目最大的感受是：状态管理方案的收益不是第一天体现的，而是第三次加功能时才体现出来的。第一次把搜索、详情的状态收编成 Cubit 时，代码量比原来多了将近三分之一，我当时也怀疑“这值得吗”。等做到收藏、历史、多语言切换，三个模块之间要互相联动的时候，才发现统一的状态流让耦合变得可控，新增一个功能只需要加一个 Cubit 加一组状态，不用回头翻原来的StatefulWidget。

有几个小技巧最后分享给需要的人。防抖的 400ms 只是一个经验值，如果你的阅读器搜索请求比较慢，调到 600ms 也不会太影响体验。HydratedBloc.storage初始化时，getApplicationDocumentsDirectory()是异步的，必须在runApp前完成，别省这个 await。还有，给 Cubit 写单元测试时，断言状态序列比最终状态更有价值，因为交互类 bug 往往发生在状态中途的跳转上。

这个系列的核心部分到这里算是齐了：环境、网络、页面、导航、状态管理都落到了实处。如果你也是一个人鼓捣内容型 App 的状态管理，照着上面这套思路拆状态、定边界、写持久化，基本后面就是优化细节的事了。