欢迎大家加入[开源鸿蒙跨平台开发者社区](https://openharmonycrossplatform.csdn.net)，一起共建开源鸿蒙跨平台生态。
在 Flutter 开发的迭代长河中，状态管理始终是绕不开的核心命题。Provider 曾凭借简洁的 API 和低学习成本成为主流选择，但随着业务复杂度提升，它的局限性逐渐暴露 —— 全局上下文依赖、类型安全不足、重构成本高、多状态组合繁琐等问题日益凸显。而 Riverpod 2.0 作为 Provider 的 “升级版”，彻底解决了这些痛点，同时保留了易用性，还新增了缓存、自动刷新、多线程支持等高级特性。本文将从实际项目痛点出发，手把手教你完成从 Provider 到 Riverpod 2.0 的无痛迁移，同时解锁 Riverpod 的高性能玩法，让状态管理既 “优雅” 又 “高效”。
一、为什么要从 Provider 迁移到 Riverpod？
先通过一张表直观对比两者的核心差异，理解迁移的价值：
| 特性 | Provider | Riverpod 2.0 |
|---|---|---|
| 上下文依赖 | 强依赖 BuildContext，无上下文无法访问 | 完全脱离 BuildContext，随处可访问 |
| 类型安全 | 依赖Provider.of<T>，类型错误运行时才暴露 | 编译期类型检查，杜绝类型错误 |
| 状态复用 | 全局单例，复用需手动封装 | 支持局部 / 全局作用域，复用更灵活 |
| 重构成本 | 改名 / 移位置需全局替换 | 基于唯一标识符，重构无感知 |
| 缓存机制 | 无原生缓存，需手动实现 | 内置缓存策略，支持自动失效 |
| 异步处理 | 需结合 FutureProvider/StreamProvider，API 繁琐 | AsyncNotifier + 自动状态管理，简化异步逻辑 |
| 性能优化 | 依赖 Consumer/Selector，优化成本高 | 细粒度重建控制，默认高性能 |
二、前置准备：环境配置与核心概念
1. 依赖引入
在pubspec.yaml中添加 Riverpod 2.0 核心依赖：
yaml
dependencies: flutter: sdk: flutter flutter_riverpod: ^2.4.9 # 核心依赖（包含Widget绑定） riverpod_annotation: ^2.3.1 # 注解支持（可选，简化代码） json_annotation: ^4.8.1 # 配合实体类序列化（可选） dev_dependencies: flutter_test: sdk: flutter build_runner: ^2.4.6 # 注解生成代码 riverpod_generator: ^2.3.3 # Riverpod注解生成器 json_serializable: ^6.7.1 # 序列化代码生成器2. 核心概念速览
Riverpod 2.0 的核心设计围绕 “提供者（Provider）” 和 “消费者（Consumer）” 展开，且完全解耦上下文：
- Provider：状态的生产者，分为
Provider（只读状态）、StateProvider（简单可变状态）、NotifierProvider（复杂状态）、AsyncNotifierProvider（异步状态）等； - Ref：状态的引用对象，用于监听 / 更新其他 Provider、获取生命周期、缓存控制等；
- ProviderScope：Riverpod 的根容器，替代 Provider 的
MultiProvider，需包裹在 App 最外层； - Consumer/ConsumerWidget：状态的消费者，用于在 Widget 中监听状态变化。
三、从 Provider 到 Riverpod 的分步迁移实战
场景：电商 App 的购物车状态管理
我们以 “购物车添加 / 删除商品” 这个典型场景为例，先展示 Provider 的实现方式，再一步步迁移到 Riverpod 2.0，并对比差异。
步骤 1：Provider 实现（旧代码）
dart
// 1. 定义购物车模型 class CartItem { final String id; final String name; final double price; int count; CartItem({ required this.id, required this.name, required this.price, this.count = 1, }); } // 2. 定义Provider final cartProvider = ChangeNotifierProvider((ref) => CartProvider()); // 3. 实现ChangeNotifier class CartProvider extends ChangeNotifier { final List<CartItem> _items = []; List<CartItem> get items => _items; // 添加商品 void addItem(CartItem item) { final index = _items.indexWhere((i) => i.id == item.id); if (index >= 0) { _items[index].count++; } else { _items.add(item); } notifyListeners(); } // 删除商品 void removeItem(String id) { _items.removeWhere((item) => item.id == id); notifyListeners(); } // 计算总价 double get totalPrice { return _items.fold(0, (sum, item) => sum + item.price * item.count); } } // 4. Widget中使用 class CartPage extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text("购物车")), body: Consumer<CartProvider>( builder: (context, cart, child) { if (cart.items.isEmpty) { return const Center(child: Text("购物车为空")); } return ListView.builder( itemCount: cart.items.length, itemBuilder: (context, index) { final item = cart.items[index]; return ListTile( title: Text(item.name), subtitle: Text("¥${item.price} x ${item.count}"), trailing: IconButton( icon: const Icon(Icons.delete, color: Colors.red), onPressed: () { cart.removeItem(item.id); }, ), ); }, ); }, ), floatingActionButton: FloatingActionButton( onPressed: () { // 添加商品（依赖上下文） Provider.of<CartProvider>(context, listen: false).addItem( CartItem( id: DateTime.now().microsecondsSinceEpoch.toString(), name: "新款T恤", price: 99.9, ), ); }, child: const Icon(Icons.add), ), ); } } // 5. 根Widget配置 void main() { runApp( ChangeNotifierProvider( create: (context) => CartProvider(), child: const MyApp(), ), ); }步骤 2：Riverpod 2.0 迁移（新代码）
第一步：重构根 Widget，添加 ProviderScope
dart
// main.dart import 'package:flutter_riverpod/flutter_riverpod.dart'; void main() { runApp( // 替代ChangeNotifierProvider，包裹整个App const ProviderScope( child: MyApp(), ), ); } class MyApp extends StatelessWidget { const MyApp({super.key}); @override Widget build(BuildContext context) { return MaterialApp( title: 'Riverpod购物车示例', home: const CartPage(), ); } }第二步：用 Notifier 重构购物车状态（核心）
dart
// cart_notifier.dart import 'package:flutter_riverpod/flutter_riverpod.dart'; // 1. 保持CartItem模型不变（无需修改） class CartItem { final String id; final String name; final double price; int count; CartItem({ required this.id, required this.name, required this.price, this.count = 1, }); } // 2. 定义Notifier（替代ChangeNotifier） class CartNotifier extends Notifier<List<CartItem>> { // 初始化状态（替代构造函数） @override List<CartItem> build() { // 可在这里执行初始化逻辑（如从本地缓存加载购物车） return []; } // 添加商品（无notifyListeners，状态更新自动通知） void addItem(CartItem item) { // 注意：必须创建新列表（不可变状态），Riverpod通过引用对比检测变化 final newItems = List<CartItem>.from(state); final index = newItems.indexWhere((i) => i.id == item.id); if (index >= 0) { // 同样创建新对象，保证不可变性 newItems[index] = CartItem( id: newItems[index].id, name: newItems[index].name, price: newItems[index].price, count: newItems[index].count + 1, ); } else { newItems.add(item); } // 更新状态 state = newItems; } // 删除商品 void removeItem(String id) { final newItems = List<CartItem>.from(state) ..removeWhere((item) => item.id == id); state = newItems; } // 计算总价（封装为计算属性，也可抽离为单独Provider） double get totalPrice { return state.fold(0, (sum, item) => sum + item.price * item.count); } } // 3. 定义Provider（全局唯一，无上下文依赖） final cartProvider = NotifierProvider<CartNotifier, List<CartItem>>(() { return CartNotifier(); }); // 4. 抽离总价为单独Provider（细粒度控制重建） final cartTotalPriceProvider = Provider<double>((ref) { // 监听购物车状态变化，仅当状态改变时重新计算 final cartItems = ref.watch(cartProvider); return cartItems.fold(0, (sum, item) => sum + item.price * item.count); });第三步：重构 Widget，脱离上下文依赖
dart
// cart_page.dart import 'package:flutter_riverpod/flutter_riverpod.dart'; // 使用ConsumerWidget替代StatelessWidget（自动关联Ref） class CartPage extends ConsumerWidget { const CartPage({super.key}); @override // 新增WidgetRef参数，用于访问Provider Widget build(BuildContext context, WidgetRef ref) { // 监听购物车状态（仅当列表变化时重建） final cartItems = ref.watch(cartProvider); // 监听总价（仅当总价变化时重建，而非列表变化就重建） final totalPrice = ref.watch(cartTotalPriceProvider); return Scaffold( appBar: AppBar( title: const Text("购物车"), // 总价仅在变化时更新，无需整个AppBar重建 actions: [ Padding( padding: const EdgeInsets.only(right: 16), child: Text("总价：¥${totalPrice.toStringAsFixed(2)}"), ) ], ), body: cartItems.isEmpty ? const Center(child: Text("购物车为空")) : ListView.builder( itemCount: cartItems.length, itemBuilder: (context, index) { final item = cartItems[index]; return ListTile( title: Text(item.name), subtitle: Text("¥${item.price} x ${item.count}"), trailing: IconButton( icon: const Icon(Icons.delete, color: Colors.red), onPressed: () { // 访问Notifier，无上下文依赖 ref.read(cartProvider.notifier).removeItem(item.id); }, ), ); }, ), floatingActionButton: FloatingActionButton( onPressed: () { // 添加商品，完全脱离上下文 ref.read(cartProvider.notifier).addItem( CartItem( id: DateTime.now().microsecondsSinceEpoch.toString(), name: "新款T恤", price: 99.9, ), ); }, child: const Icon(Icons.add), ), ); } }步骤 3：关键差异解析
状态不可变性：Provider 中直接修改
_items并调用notifyListeners()，而 Riverpod 要求状态不可变 —— 必须创建新列表 / 新对象更新state，这避免了隐式状态修改，提升代码可维护性。上下文解耦：Provider 的
Provider.of/Consumer强依赖BuildContext，而 Riverpod 通过WidgetRef访问状态，可在任意位置（如工具类、异步函数）调用ref.read(cartProvider)，无需上下文。细粒度重建：将 “总价” 抽离为单独的
cartTotalPriceProvider，仅当总价变化时，AppBar 的价格文本才重建，而 Provider 中只要购物车列表变化，整个 Consumer 包裹的区域都会重建。类型安全：Riverpod 的
ref.watch(cartProvider)编译期就确定返回List<CartItem>，而 Provider 的Provider.of<CartProvider>若类型写错，只有运行时才会报错。
四、Riverpod 2.0 高级特性：解锁高性能状态管理
1. 异步状态管理（AsyncNotifier）
在实际项目中，购物车通常需要从网络 / 本地缓存加载，Riverpod 的AsyncNotifier简化了异步状态处理：
dart
// 1. 定义异步Notifier class AsyncCartNotifier extends AsyncNotifier<List<CartItem>> { // 模拟从本地缓存加载购物车 Future<List<CartItem>> _loadCartFromLocal() async { await Future.delayed(const Duration(seconds: 1)); // 模拟耗时操作 // 实际项目中可从SharedPreferences/SQLite读取 return [ CartItem(id: "1", name: "默认商品", price: 59.9), ]; } @override Future<List<CartItem>> build() async { // 初始化时自动加载数据，状态自动转为AsyncValue.loading/error/data return _loadCartFromLocal(); } // 添加商品并同步到本地 Future<void> addItem(CartItem item) async { // 标记为加载中 state = const AsyncValue.loading(); try { final currentItems = state.value ?? []; final newItems = List<CartItem>.from(currentItems); final index = newItems.indexWhere((i) => i.id == item.id); if (index >= 0) { newItems[index] = CartItem( id: newItems[index].id, name: newItems[index].name, price: newItems[index].price, count: newItems[index].count + 1, ); } else { newItems.add(item); } // 模拟同步到本地 await Future.delayed(const Duration(milliseconds: 500)); // 更新状态 state = AsyncValue.data(newItems); } catch (e) { // 捕获异常，状态自动转为error state = AsyncValue.error(e, StackTrace.current); } } } // 2. 定义异步Provider final asyncCartProvider = AsyncNotifierProvider<AsyncCartNotifier, List<CartItem>>(() { return AsyncCartNotifier(); }); // 3. Widget中使用 class AsyncCartPage extends ConsumerWidget { const AsyncCartPage({super.key}); @override Widget build(BuildContext context, WidgetRef ref) { // 监听异步状态，自动处理loading/error/data final cartAsyncValue = ref.watch(asyncCartProvider); return Scaffold( appBar: AppBar(title: const Text("异步购物车")), body: cartAsyncValue.when( loading: () => const Center(child: CircularProgressIndicator()), error: (error, stack) => Center(child: Text("加载失败：$error")), data: (cartItems) { if (cartItems.isEmpty) { return const Center(child: Text("购物车为空")); } return ListView.builder( itemCount: cartItems.length, itemBuilder: (context, index) { final item = cartItems[index]; return ListTile(title: Text(item.name)); }, ); }, ), ); } }2. 缓存与自动刷新
Riverpod 支持缓存状态，并可通过ref.refresh/ref.invalidate手动刷新，或设置自动刷新：
dart
// 定义带缓存的商品列表Provider final productListProvider = FutureProvider<List<String>>((ref) async { // 设置缓存时间（5秒），5秒后自动失效刷新 ref.keepAliveFor(const Duration(seconds: 5)); // 模拟网络请求 await Future.delayed(const Duration(seconds: 1)); return ["商品1", "商品2", "商品3"]; }); // Widget中手动刷新 class ProductPage extends ConsumerWidget { const ProductPage({super.key}); @override Widget build(BuildContext context, WidgetRef ref) { final productsAsync = ref.watch(productListProvider); return Scaffold( appBar: AppBar(title: const Text("商品列表")), body: productsAsync.when( loading: () => const Center(child: CircularProgressIndicator()), error: (e, s) => Text("错误：$e"), data: (products) => ListView.builder( itemCount: products.length, itemBuilder: (_, i) => ListTile(title: Text(products[i])), ), ), floatingActionButton: FloatingActionButton( onPressed: () { // 手动刷新商品列表 ref.refresh(productListProvider); }, child: const Icon(Icons.refresh), ), ); } }3. 局部作用域（避免全局状态污染）
Provider 的状态默认全局，而 Riverpod 支持局部作用域，比如为每个页面创建独立的购物车状态：
dart
class ScopedCartPage extends ConsumerWidget { const ScopedCartPage({super.key}); @override Widget build(BuildContext context, WidgetRef ref) { return ProviderScope( // 覆盖全局cartProvider，创建局部状态 overrides: [ cartProvider.overrideWith(() => CartNotifier()), ], child: const CartPage(), // 复用之前的CartPage，使用局部状态 ); } }五、迁移避坑指南
1. 常见问题与解决方案
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 状态更新后 Widget 不重建 | 直接修改 state 对象（未创建新对象） | 确保状态不可变，更新时创建新列表 / 新对象 |
| 报错 “Provider not found” | 未添加 ProviderScope 根容器 | 在 runApp 中包裹 ProviderScope |
| 上下文为空报错 | 仍在使用 BuildContext 访问状态 | 替换为 WidgetRef.read/watch |
| 性能反而下降 | 过度使用 ref.watch，导致频繁重建 | 抽离细粒度 Provider，使用 select 筛选状态 |
2. 性能优化技巧
- 使用 select 筛选状态：仅监听需要的状态字段，避免全量重建：
dart
// 仅监听购物车商品数量，而非整个列表 final itemCount = ref.watch(cartProvider.select((items) => items.length)); - 延迟加载：使用
ref.watch(provider.notifier)仅获取通知器，不监听状态； - 避免在 build 中执行耗时操作：将异步逻辑封装在 Notifier 的 build/addItem 中；
- 使用 keepAlive：对高频访问的状态设置
ref.keepAlive，避免重复初始化。
六、总结
从 Provider 到 Riverpod 2.0 的迁移，本质上是从 “命令式、上下文绑定、可变状态” 向 “声明式、上下文解耦、不可变状态” 的思维转变。Riverpod 2.0 不仅解决了 Provider 的核心痛点，还通过异步状态管理、细粒度重建、缓存机制等特性，大幅提升了状态管理的性能和可维护性。
本文的迁移方案可直接落地到实际项目：
- 先替换根容器为
ProviderScope； - 逐步将
ChangeNotifierProvider重构为NotifierProvider； - 将 Widget 中的
Consumer/Provider.of替换为ConsumerWidget+WidgetRef； - 利用 Riverpod 的高级特性（AsyncNotifier、缓存、局部作用域）优化性能。
相比于 Provider，Riverpod 2.0 的学习曲线稍高，但一旦掌握，会显著降低大型项目的状态管理复杂度。最后，附上完整示例代码仓库（示例）：https://github.com/xxx/flutter_riverpod_migration，欢迎大家 Star、Fork，也欢迎在评论区交流迁移过程中遇到的问题和优化思路！
