Riverpod 实战指南

Riverpod 实战指南

本文不堆概念，用 9 个递进的完整场景 把 Riverpod 讲透。

每个场景给出 完整可运行代码 + 运行效果 + 踩坑点 。

建议边读边敲，不要只看。

基于 flutter_riverpod: ^2.6.x（Riverpod 2），文末附 Riverpod 3 迁移要点。

---

准备工作

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^2.6.1
  riverpod_annotation: ^2.6.1
  http: ^1.2.0
  freezed_annotation: ^2.4.1

dev_dependencies:
  riverpod_generator: ^2.6.2
  build_runner: ^2.4.0
  freezed: ^2.5.2
  json_serializable: ^6.7.1
  flutter_test:
    sdk: flutter

# 生成代码（一直跑着）
dart run build_runner watch -d

入口固定写法（后面每个场景都假设已有这段）：

// main.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

void main() {
  runApp(const ProviderScope(child: MyApp()));
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Riverpod Demo',
      theme: ThemeData(useMaterial3: true, colorSchemeSeed: Colors.blue),
      home: const HomePage(), // 替换成各场景页面
    );
  }
}

---

场景 1：主题切换 ------ 最小的「跨组件共享状态」

需求：页面顶部一个开关切换深色/浅色模式，底部文字实时响应。

完整代码

// theme_provider.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';

// StateProvider 适合"一个布尔值、一个枚举"级别的极简状态
final isDarkModeProvider = StateProvider<bool>((ref) => false);

// theme_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'theme_provider.dart';

class ThemePage extends ConsumerWidget {
  const ThemePage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // ① watch：build 里订阅，值变 → 自动重建
    // 🔄 刷新范围：isDark 变化 → 整个 ThemePage.build() 重跑
    //    → Scaffold、Switch、Text 全部重建（因为 watch 写在最顶层）
    final isDark = ref.watch(isDarkModeProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('场景1：主题切换')),
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Switch(
              value: isDark,
              onChanged: (v) {
                // ② read：事件回调里只"读一次"并修改，不建立订阅
                ref.read(isDarkModeProvider.notifier).state = v;
              },
            ),
            const SizedBox(height: 20),
            Text(
              isDark ? '当前是深色模式 🌙' : '当前是浅色模式 ☀️',
              style: const TextStyle(fontSize: 24),
            ),
          ],
        ),
      ),
    );
  }
}

学到什么

要点	说明
ref.watch	写在 build 里，状态变了界面自动刷新
ref.read	写在 onChanged / onPressed 里，只读一次去改值
StateProvider	一个值、没有业务方法时够用

反面教材

// ❌ 在 build 里用 read → 界面永远不会因为 isDarkMode 变化而刷新
final isDark = ref.read(isDarkModeProvider);

---

场景 2：待办清单 ------ 有业务方法的状态用 Notifier

需求：添加待办、标记完成、删除。比一个布尔值复杂，需要方法。

完整代码

// todo_model.dart
class Todo {
  final String id;
  final String title;
  final bool completed;

  Todo({required this.id, required this.title, this.completed = false});

  Todo copyWith({String? title, bool? completed}) {
    return Todo(
      id: id,
      title: title ?? this.title,
      completed: completed ?? this.completed,
    );
  }
}

// todo_notifier.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'todo_model.dart';

class TodoListNotifier extends Notifier<List<Todo>> {
  @override
  List<Todo> build() => []; // 初始状态：空列表

  void add(String title) {
    // 不可变更新：创建新 list
    state = [
      ...state,
      Todo(id: DateTime.now().millisecondsSinceEpoch.toString(), title: title),
    ];
  }

  void toggle(String id) {
    state = [
      for (final todo in state)
        if (todo.id == id) todo.copyWith(completed: !todo.completed) else todo,
    ];
  }

  void remove(String id) {
    state = state.where((t) => t.id != id).toList();
  }
}

final todoListProvider =
    NotifierProvider<TodoListNotifier, List<Todo>>(TodoListNotifier.new);

// 派生 Provider：已完成数量（只读、自动跟随 todoList 变化）
final completedCountProvider = Provider<int>((ref) {
  final todos = ref.watch(todoListProvider);
  return todos.where((t) => t.completed).length;
});

// todo_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'todo_notifier.dart';

class TodoPage extends ConsumerWidget {
  const TodoPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：todoListProvider 或 completedCountProvider 任一变化
    //    → 整个 TodoPage.build() 重跑
    //    → AppBar(计数文字) + ListView(所有 ListTile) 全部重建
    //    → FloatingActionButton 也重建（但 const Icon 会被 Flutter 复用）
    final todos = ref.watch(todoListProvider);
    final doneCount = ref.watch(completedCountProvider);

    return Scaffold(
      appBar: AppBar(title: Text('待办 (已完成 $doneCount/${todos.length})')),
      body: ListView.builder(
        itemCount: todos.length,
        itemBuilder: (_, i) {
          final todo = todos[i];
          return ListTile(
            leading: Checkbox(
              value: todo.completed,
              onChanged: (_) =>
                  ref.read(todoListProvider.notifier).toggle(todo.id),
            ),
            title: Text(
              todo.title,
              style: TextStyle(
                decoration:
                    todo.completed ? TextDecoration.lineThrough : null,
              ),
            ),
            trailing: IconButton(
              icon: const Icon(Icons.delete),
              onPressed: () =>
                  ref.read(todoListProvider.notifier).remove(todo.id),
            ),
          );
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => _showAddDialog(context, ref),
        child: const Icon(Icons.add),
      ),
    );
  }

  void _showAddDialog(BuildContext context, WidgetRef ref) {
    final controller = TextEditingController();
    showDialog(
      context: context,
      builder: (_) => AlertDialog(
        title: const Text('添加待办'),
        content: TextField(controller: controller, autofocus: true),
        actions: [
          TextButton(
            onPressed: () {
              if (controller.text.isNotEmpty) {
                ref.read(todoListProvider.notifier).add(controller.text);
              }
              Navigator.pop(context);
            },
            child: const Text('确定'),
          ),
        ],
      ),
    );
  }
}

学到什么

要点	说明
Notifier	状态有"动作"（add/toggle/remove）时用它，比 StateProvider 清晰
state = ...	必须整体赋新值（不可变更新），Riverpod 才能检测到变化
派生 Provider	completedCountProvider 自动跟随 todoListProvider，不需要手动同步
.notifier	在回调里 ref.read(xxx.notifier).method() 调用业务方法

踩坑点

// ❌ 直接 mutate list → Riverpod 检测不到变化，界面不刷新
void add(String title) {
  state.add(Todo(...)); // 错！引用没变
}

// ✅ 赋新 list
void add(String title) {
  state = [...state, Todo(...)];
}

---

场景 3：网络请求 ------ FutureProvider + Loading/Error/Data 三态

需求：从网络拉取用户列表，显示加载中 → 数据 → 出错三种状态。

完整代码

// user_model.dart
class User {
  final int id;
  final String name;
  final String email;

  User({required this.id, required this.name, required this.email});

  factory User.fromJson(Map<String, dynamic> json) => User(
        id: json['id'] as int,
        name: json['name'] as String,
        email: json['email'] as String,
      );
}

// user_repository.dart
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'user_model.dart';

class UserRepository {
  Future<List<User>> fetchUsers() async {
    final response = await http.get(
      Uri.parse('https://jsonplaceholder.typicode.com/users'),
    );
    if (response.statusCode != 200) {
      throw Exception('请求失败: ${response.statusCode}');
    }
    final list = jsonDecode(response.body) as List;
    return list.map((e) => User.fromJson(e as Map<String, dynamic>)).toList();
  }
}

// user_providers.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'user_repository.dart';
import 'user_model.dart';

// 依赖注入：Repository 本身也是 Provider，方便测试时替换
final userRepositoryProvider = Provider<UserRepository>((ref) {
  return UserRepository();
});

// FutureProvider：声明"这个数据怎么来"，框架管 loading/error/data
final userListProvider = FutureProvider<List<User>>((ref) async {
  final repo = ref.watch(userRepositoryProvider);
  return repo.fetchUsers();
});

// user_list_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'user_providers.dart';

class UserListPage extends ConsumerWidget {
  const UserListPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：userListProvider 状态切换（loading → data → error）
    //    → 整个 UserListPage.build() 重跑
    //    → body 在 CircularProgressIndicator / ListView / 错误提示 之间切换
    //    → AppBar 不受数据影响（标题是 const），但仍在 build 树内会被重建
    final usersAsync = ref.watch(userListProvider);

    return Scaffold(
      appBar: AppBar(
        title: const Text('场景3：网络请求'),
        actions: [
          // 下拉刷新：invalidate 让 Provider 重新执行
          IconButton(
            icon: const Icon(Icons.refresh),
            onPressed: () => ref.invalidate(userListProvider),
          ),
        ],
      ),
      // .when 一次性处理三种状态，编译器保证你不遗漏
      body: usersAsync.when(
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (err, stack) => Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              Text('出错了: $err'),
              const SizedBox(height: 8),
              ElevatedButton(
                onPressed: () => ref.invalidate(userListProvider),
                child: const Text('重试'),
              ),
            ],
          ),
        ),
        data: (users) => ListView.builder(
          itemCount: users.length,
          itemBuilder: (_, i) => ListTile(
            leading: CircleAvatar(child: Text('${users[i].id}')),
            title: Text(users[i].name),
            subtitle: Text(users[i].email),
          ),
        ),
      ),
    );
  }
}

学到什么

要点	说明
FutureProvider	声明"数据怎么来"，自动管理 loading/error/data 生命周期
AsyncValue.when	三态分支，编译器强制你每个都处理，不会漏
ref.invalidate	让缓存失效，Provider 重新执行（用于刷新/重试）
Repository 注入	userRepositoryProvider 让测试时可以 override 成假实现

踩坑点

// ❌ 只判断 data，忘了 loading 和 error → 白屏
body: Text(usersAsync.value?.first.name ?? ''),

// ✅ 用 .when 或 .maybeWhen 显式处理每种状态

---

场景 4：详情页 ------ family 按参数缓存 + autoDispose 自动释放

需求：列表点击进入用户详情页，每个用户 ID 对应独立缓存；离开页面自动释放。

完整代码

// user_detail_provider.dart
import 'dart:convert';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:http/http.dart' as http;
import 'user_model.dart';

// .family：按 userId 参数化，每个 id 一份独立缓存
// .autoDispose：没人看这个详情页时，自动释放缓存
final userDetailProvider =
    FutureProvider.autoDispose.family<User, int>((ref, userId) async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/users/$userId'),
  );
  if (response.statusCode != 200) throw Exception('请求失败');
  return User.fromJson(jsonDecode(response.body) as Map<String, dynamic>);
});

// user_detail_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'user_detail_provider.dart';

class UserDetailPage extends ConsumerWidget {
  final int userId;
  const UserDetailPage({super.key, required this.userId});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：该 userId 对应的数据状态变化（loading → data）
    //    → 整个 UserDetailPage.build() 重跑
    //    → body 从 CircularProgressIndicator 切换到用户详情
    //    → 其他 userId 的 Provider 变化不影响这个页面
    final detailAsync = ref.watch(userDetailProvider(userId));

    return Scaffold(
      appBar: AppBar(title: Text('用户 #$userId')),
      body: detailAsync.when(
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (e, _) => Center(child: Text('$e')),
        data: (user) => Padding(
          padding: const EdgeInsets.all(24),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              Text(user.name, style: const TextStyle(fontSize: 28)),
              const SizedBox(height: 8),
              Text(user.email, style: const TextStyle(fontSize: 18)),
              const SizedBox(height: 24),
              const Text(
                '💡 返回列表后，这个 Provider 会自动释放\n'
                '   再次进入会重新请求',
              ),
            ],
          ),
        ),
      ),
    );
  }
}

从场景 3 的列表页跳转：

// 在 user_list_page.dart 的 ListTile 加 onTap
onTap: () => Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => UserDetailPage(userId: users[i].id),
  ),
),

学到什么

要点	说明
.family	一个 Provider 定义 → 按参数生成 N 个独立实例
.autoDispose	页面 pop 后无人 watch → 自动释放，不留内存
组合链	FutureProvider.autoDispose.family ------ 这三个能力可以自由组合

踩坑点

// ❌ family 参数用了复杂对象，但没实现 == 和 hashCode
//    → 每次 build 都认为是"新参数"，无限重建
final p = FutureProvider.family<Data, MyFilter>((ref, filter) { ... });

// ✅ family 参数优先用基本类型（int, String, enum）
//    复杂参数务必正确实现 == / hashCode（推荐用 freezed）

---

场景 5：登录认证 ------ AsyncNotifier + listen 做副作用 + 依赖链

需求 ：登录表单 → 提交 → 加载中 → 成功后自动跳转首页 / 失败显示错误。

这是把前面学到的东西串起来的「综合场景」。

完整代码

// auth_state.dart
class AuthState {
  final String? token;
  final String? username;

  const AuthState({this.token, this.username});

  bool get isLoggedIn => token != null;
}

// auth_notifier.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'auth_state.dart';

class AuthNotifier extends AsyncNotifier<AuthState> {
  @override
  Future<AuthState> build() async {
    // 初始状态：未登录（实际项目这里可以读本地 token）
    return const AuthState();
  }

  Future<void> login(String username, String password) async {
    // 先切到 loading 状态
    state = const AsyncLoading();

    // AsyncValue.guard 自动把异常转为 AsyncError
    state = await AsyncValue.guard(() async {
      // 模拟网络请求
      await Future.delayed(const Duration(seconds: 2));

      if (password != '123456') {
        throw Exception('密码错误');
      }

      return AuthState(token: 'fake_token_abc', username: username);
    });
  }

  void logout() {
    state = const AsyncData(AuthState());
  }
}

final authProvider =
    AsyncNotifierProvider<AuthNotifier, AuthState>(AuthNotifier.new);

// 派生：当前是否已登录（其他地方只关心这个布尔值）
final isLoggedInProvider = Provider<bool>((ref) {
  return ref.watch(authProvider).valueOrNull?.isLoggedIn ?? false;
});

// login_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'auth_notifier.dart';

class LoginPage extends ConsumerStatefulWidget {
  const LoginPage({super.key});
  @override
  ConsumerState<LoginPage> createState() => _LoginPageState();
}

class _LoginPageState extends ConsumerState<LoginPage> {
  final _userCtrl = TextEditingController(text: 'admin');
  final _passCtrl = TextEditingController();

  @override
  void dispose() {
    _userCtrl.dispose();
    _passCtrl.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    // 🔄 刷新范围：authProvider 变化（未登录 → loading → 已登录/错误）
    //    → 整个 _LoginPageState.build() 重跑
    //    → ElevatedButton：loading 时变 disabled + 显示转圈
    //    → TextField 不受影响（由 TextEditingController 自己管理内容）
    final authState = ref.watch(authProvider);

    // ③ listen：监听状态变化做副作用（跳转）
    // ⚠️ listen 不触发 build 重建！它只在值变化时执行回调
    //    跳转和 SnackBar 是"副作用"，不是 UI 重建
    ref.listen(authProvider, (prev, next) {
      // 登录成功 → 跳转
      if (next.valueOrNull?.isLoggedIn == true) {
        Navigator.pushReplacement(
          context,
          MaterialPageRoute(builder: (_) => const HomePage()),
        );
      }
      // 登录失败 → 弹错误提示
      if (next.hasError) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('${next.error}')),
        );
      }
    });

    final isLoading = authState is AsyncLoading;

    return Scaffold(
      appBar: AppBar(title: const Text('场景5：登录')),
      body: Padding(
        padding: const EdgeInsets.all(24),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            TextField(
              controller: _userCtrl,
              decoration: const InputDecoration(labelText: '用户名'),
            ),
            const SizedBox(height: 12),
            TextField(
              controller: _passCtrl,
              obscureText: true,
              decoration: const InputDecoration(
                labelText: '密码',
                hintText: '输入 123456 登录成功',
              ),
            ),
            const SizedBox(height: 24),
            SizedBox(
              width: double.infinity,
              child: ElevatedButton(
                onPressed: isLoading
                    ? null
                    : () => ref.read(authProvider.notifier).login(
                          _userCtrl.text,
                          _passCtrl.text,
                        ),
                child: isLoading
                    ? const SizedBox(
                        height: 20,
                        width: 20,
                        child: CircularProgressIndicator(strokeWidth: 2),
                      )
                    : const Text('登录'),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

class HomePage extends ConsumerWidget {
  const HomePage({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：authProvider 变化 → 整个 HomePage.build() 重跑
    //    → AppBar title 更新用户名
    //    → body 是 const，Flutter 会复用，但仍在 build 产出树内
    final auth = ref.watch(authProvider).valueOrNull;
    return Scaffold(
      appBar: AppBar(
        title: Text('欢迎, ${auth?.username ?? ""}'),
        actions: [
          IconButton(
            icon: const Icon(Icons.logout),
            onPressed: () {
              ref.read(authProvider.notifier).logout();
              Navigator.pushReplacement(
                context,
                MaterialPageRoute(builder: (_) => const LoginPage()),
              );
            },
          ),
        ],
      ),
      body: const Center(child: Text('登录成功！', style: TextStyle(fontSize: 24))),
    );
  }
}

学到什么

要点	说明
AsyncNotifier	有异步方法（login）的状态用它，自带 loading/error/data 生命周期
AsyncValue.guard	一行代码把 try/catch 变成 AsyncData 或 AsyncError
ref.listen	副作用 （跳转、SnackBar）放这里，不是 放在 build 返回的 Widget 树里
派生 Provider	isLoggedInProvider 只暴露布尔值，其他页面不需要知道 token 细节
ConsumerStatefulWidget	需要 TextEditingController 等有生命周期的东西时用它

watch / read / listen 完整对照

┌──────────────────────────────────────────────────────────────┐
│                      build() 方法体                          │
│                                                              │
│   ref.watch(authProvider)  ← 订阅，值变了 build 重跑         │
│   ref.listen(authProvider, callback)  ← 订阅，值变了跑回调   │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                   onPressed / 事件回调                        │
│                                                              │
│   ref.read(authProvider.notifier).login(...)  ← 读一次，调方法│
│                                                              │
└──────────────────────────────────────────────────────────────┘

---

场景 6：搜索 + 防抖 ------ 多 Provider 协作的真实模式

需求 ：搜索框输入关键词 → 防抖 500ms → 发请求 → 显示结果。

展示多个 Provider 组合成链的典型做法。

完整代码

// search_providers.dart
import 'dart:async';
import 'dart:convert';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:http/http.dart' as http;

// ① 搜索关键词（UI 写入，下游 watch）
final searchQueryProvider = StateProvider<String>((ref) => '');

// ② 防抖后的关键词
final debouncedQueryProvider = FutureProvider.autoDispose<String>((ref) async {
  final query = ref.watch(searchQueryProvider);

  // 关键：等 500ms；如果 500ms 内 searchQueryProvider 又变了，
  // 这个 Provider 会被 dispose 重建 → 旧的 Future 被丢弃 → 天然防抖
  await Future.delayed(const Duration(milliseconds: 500));

  // 如果这里 Provider 已被 dispose（用户又输入了），不会继续往下
  return query;
});

// ③ 搜索结果（依赖防抖后的关键词）
final searchResultsProvider =
    FutureProvider.autoDispose<List<String>>((ref) async {
  // watch 防抖后的值；它是 AsyncValue，用 .value 取实际值
  final query = await ref.watch(debouncedQueryProvider.future);

  if (query.isEmpty) return [];

  // 用 JSONPlaceholder 模拟搜索
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/users?username=$query'),
  );
  final list = jsonDecode(response.body) as List;
  return list.map((e) => '${e["name"]} (${e["email"]})').toList();
});

// search_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'search_providers.dart';

class SearchPage extends ConsumerWidget {
  const SearchPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：searchResultsProvider 变化（防抖结束 → 请求中 → 拿到结果）
    //    → 整个 SearchPage.build() 重跑
    //    → Expanded 区域在 loading 转圈 / 结果列表 / "无结果" 之间切换
    //    ⚠️ TextField 不受影响：它通过 ref.read 写入 searchQueryProvider，
    //       自己不 watch 任何 Provider，所以搜索结果变化不会导致输入框重建或丢失焦点
    final resultsAsync = ref.watch(searchResultsProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('场景6：搜索防抖')),
      body: Column(
        children: [
          Padding(
            padding: const EdgeInsets.all(16),
            child: TextField(
              decoration: const InputDecoration(
                hintText: '试试输入 Bret 或 Delphine',
                prefixIcon: Icon(Icons.search),
              ),
              onChanged: (value) {
                // 写入搜索关键词 → 触发整条依赖链
                ref.read(searchQueryProvider.notifier).state = value;
              },
            ),
          ),
          Expanded(
            child: resultsAsync.when(
              loading: () => const Center(child: CircularProgressIndicator()),
              error: (e, _) => Center(child: Text('搜索出错: $e')),
              data: (results) => results.isEmpty
                  ? const Center(child: Text('无结果'))
                  : ListView.builder(
                      itemCount: results.length,
                      itemBuilder: (_, i) => ListTile(
                        leading: const Icon(Icons.person),
                        title: Text(results[i]),
                      ),
                    ),
            ),
          ),
        ],
      ),
    );
  }
}

依赖链图

用户输入
   ↓
searchQueryProvider (StateProvider<String>)
   ↓  watch
debouncedQueryProvider (FutureProvider, 500ms 延迟)
   ↓  watch
searchResultsProvider (FutureProvider, 发请求)
   ↓  watch
SearchPage UI (显示结果)

学到什么

要点	说明
Provider 链	复杂逻辑拆成多个 Provider，每个只做一件事
autoDispose 实现防抖	上游变化 → 旧 Provider dispose → 新 Provider 重新等 500ms
数据流可追溯	出 bug 时沿着链条一个一个检查，而不是在一坨代码里找

---

场景 7：实时数据 ------ StreamProvider 监听持续变化

需求：页面实时接收服务器推送事件（类似 WebSocket / Firebase / SSE），展示连接状态 + 累积的消息历史。离开页面后自动断开连接。

这是 FutureProvider（一次性拉取）覆盖不了的场景------数据是连续推过来的。

完整代码

// live_event.dart
class LiveEvent {
  final int id;
  final String content;
  final DateTime time;

  LiveEvent({required this.id, required this.content, required this.time});
}

// live_event_provider.dart
import 'dart:async';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'live_event.dart';

// 模拟服务器推送（实际项目替换为 WebSocket / Firebase / SSE 连接）
Stream<LiveEvent> _connectToServer() async* {
  const contents = [
    '新订单 #1024',
    '用户A发来消息',
    '库存预警：商品B不足10件',
    '支付成功：¥299.00',
    '系统维护提醒',
  ];
  for (var i = 0;; i++) {
    await Future.delayed(const Duration(seconds: 2));
    yield LiveEvent(
      id: i,
      content: contents[i % contents.length],
      time: DateTime.now(),
    );
  }
}

// StreamProvider：声明"数据流怎么来"，框架自动管理订阅和取消
// autoDispose：离开页面 → 无人 watch → 自动取消 stream 订阅
final liveEventProvider = StreamProvider.autoDispose<LiveEvent>((ref) {
  ref.onDispose(() {
    // 实际项目：关闭 WebSocket 连接、释放资源
    print('实时连接已关闭');
  });
  return _connectToServer();
});

// live_event_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'live_event_provider.dart';
import 'live_event.dart';

class LiveEventPage extends ConsumerStatefulWidget {
  const LiveEventPage({super.key});
  @override
  ConsumerState<LiveEventPage> createState() => _LiveEventPageState();
}

class _LiveEventPageState extends ConsumerState<LiveEventPage> {
  // StreamProvider 只持有"最新一条"，历史记录用局部 state 累积
  final List<LiveEvent> _history = [];

  @override
  Widget build(BuildContext context) {
    // 🔄 刷新范围：每次 stream 推送新事件 → 整个 _LiveEventPageState.build() 重跑
    //    → 顶部 Container（连接状态颜色+文字）更新
    //    → AppBar title（计数）更新
    //    → ListView（历史记录）更新
    final latestAsync = ref.watch(liveEventProvider);

    // listen：每来一条新事件，追加到历史列表
    // ⚠️ listen 本身不触发 build；但它内部的 setState(() => _history.insert(...))
    //    会触发 StatefulWidget 自己的重建。两次重建（watch + setState）
    //    在同一帧内被 Flutter 合并，实际只执行一次 build
    ref.listen(liveEventProvider, (prev, next) {
      final event = next.valueOrNull;
      if (event != null && !_history.any((e) => e.id == event.id)) {
        setState(() => _history.insert(0, event));
      }
    });

    return Scaffold(
      appBar: AppBar(title: Text('实时事件（${_history.length} 条）')),
      body: Column(
        children: [
          // 顶部：连接状态指示
          Container(
            width: double.infinity,
            padding: const EdgeInsets.all(16),
            color: latestAsync.when(
              loading: () => Colors.orange.shade100,
              error: (_, __) => Colors.red.shade100,
              data: (_) => Colors.green.shade100,
            ),
            child: latestAsync.when(
              loading: () => const Row(
                children: [
                  SizedBox(
                    width: 16,
                    height: 16,
                    child: CircularProgressIndicator(strokeWidth: 2),
                  ),
                  SizedBox(width: 8),
                  Text('正在连接服务器...'),
                ],
              ),
              error: (e, _) => Text('连接断开: $e'),
              data: (event) => Text(
                '最新: ${event.content}',
                style: const TextStyle(fontWeight: FontWeight.bold),
              ),
            ),
          ),
          // 下方：历史记录
          Expanded(
            child: _history.isEmpty
                ? const Center(child: Text('等待事件推送...'))
                : ListView.builder(
                    itemCount: _history.length,
                    itemBuilder: (_, i) {
                      final e = _history[i];
                      final t = e.time;
                      return ListTile(
                        leading: CircleAvatar(child: Text('${e.id}')),
                        title: Text(e.content),
                        subtitle: Text(
                          '${t.hour.toString().padLeft(2, '0')}:'
                          '${t.minute.toString().padLeft(2, '0')}:'
                          '${t.second.toString().padLeft(2, '0')}',
                        ),
                      );
                    },
                  ),
          ),
        ],
      ),
    );
  }
}

FutureProvider vs StreamProvider 对比

FutureProvider（场景 3）          StreamProvider（场景 7）
┌─────────────────────┐          ┌─────────────────────┐
│  请求 ──→ 等待 ──→ 结果 │          │  订阅 ──→ 事件1      │
│       （一次性）      │          │         ──→ 事件2      │
│                     │          │         ──→ 事件3      │
│                     │          │         ──→ ...持续    │
└─────────────────────┘          └─────────────────────┘
  用于：GET 接口、配置加载           用于：WebSocket、Firebase、
        一次拉取的数据                    实时推送、传感器数据

学到什么

要点	说明
StreamProvider	声明"流怎么来"，框架自动订阅/取消，暴露 AsyncValue
ref.onDispose	Provider 销毁时的清理回调，用于关闭连接、释放资源
autoDispose + Stream	离开页面 → 无人 watch → Provider 销毁 → Stream 取消 → 不泄漏
watch + listen 配合	watch 驱动 UI 刷新，listen 处理"累积历史"这种副作用

踩坑点

// ❌ 忘了 autoDispose → 离开页面后 stream 还在跑，浪费资源
final provider = StreamProvider<Event>((ref) => myStream);

// ✅ 加 autoDispose，离开页面自动取消
final provider = StreamProvider.autoDispose<Event>((ref) => myStream);

// ❌ 想在 StreamProvider 里累积历史 → 做不到，它只持有最新值
final historyProvider = StreamProvider<List<Event>>((ref) => ...);
// 每次 stream 发一个 event，你拿到的是单个 event 不是列表

// ✅ StreamProvider 拿最新值 + 另一个 Notifier/StatefulWidget 累积
//    就像上面例子中 ref.listen + setState 的做法

---

场景 8（番外）：测试 ------ Riverpod 的「高级价值」

前面 7 个场景都能用别的方案做，但测试体验是 Riverpod 真正拉开差距的地方。

// 纯逻辑测试，不需要 Flutter、不需要 Widget、不需要模拟器
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'todo_notifier.dart';

void main() {
  test('添加待办', () {
    // 创建一个独立容器，和 app 完全隔离
    final container = ProviderContainer();
    addTearDown(container.dispose);

    expect(container.read(todoListProvider), isEmpty);

    container.read(todoListProvider.notifier).add('买牛奶');
    expect(container.read(todoListProvider), hasLength(1));
    expect(container.read(todoListProvider).first.title, '买牛奶');
  });

  test('完成数量自动更新', () {
    final container = ProviderContainer();
    addTearDown(container.dispose);

    container.read(todoListProvider.notifier).add('任务A');
    container.read(todoListProvider.notifier).add('任务B');
    expect(container.read(completedCountProvider), 0);

    final id = container.read(todoListProvider).first.id;
    container.read(todoListProvider.notifier).toggle(id);
    expect(container.read(completedCountProvider), 1);
  });

  test('替换 Repository 做假数据测试', () async {
    final container = ProviderContainer(
      overrides: [
        // 把真 Repository 换成假的，不发网络请求
        userRepositoryProvider.overrideWithValue(FakeUserRepository()),
      ],
    );
    addTearDown(container.dispose);

    final users = await container.read(userListProvider.future);
    expect(users.first.name, 'Fake User');
  });
}

// 假实现
class FakeUserRepository implements UserRepository {
  @override
  Future<List<User>> fetchUsers() async {
    return [User(id: 1, name: 'Fake User', email: 'fake@test.com')];
  }
}

核心优势 ：ProviderContainer 在纯 Dart 环境下工作，不需要 pumpWidget，测试跑得快；overrides 让你能替换任何一层依赖，不需要全局 mock 框架。

---

场景 9：模块化开发 ------ 主项目与子插件之间的状态同步

需求 ：团队按业务拆包，主项目（app）和多个子插件（package）独立开发。

子插件需要读主项目的状态（比如登录用户信息），主项目也要响应子插件的状态变化（比如购物车数量）。
关键约束：子插件不能 import 主项目代码，否则就不叫"独立"了。

目录结构

my_flutter_app/               ← 主项目
├── lib/
│   ├── main.dart
│   ├── auth/
│   │   └── auth_providers.dart      ← 主项目持有登录状态
│   └── app_providers.dart           ← 组装所有模块的 overrides
│
├── packages/
│   ├── core_shared/           ← 共享层：只放接口和数据模型，不放实现
│   │   └── lib/
│   │       ├── models/
│   │       │   └── user_info.dart
│   │       └── providers/
│   │           ├── shared_auth_provider.dart    ← 抽象 Provider（占位）
│   │           └── shared_cart_provider.dart    ← 抽象 Provider（占位）
│   │
│   ├── feature_profile/       ← 子插件A：个人中心
│   │   └── lib/
│   │       └── profile_page.dart    ← watch 共享层的 Provider
│   │
│   └── feature_cart/          ← 子插件B：购物车
│       └── lib/
│           ├── cart_notifier.dart    ← 购物车业务逻辑
│           └── cart_page.dart

核心思路：三层

┌──────────────────────────────────────────────────────┐
│  主项目 (app)                                         │
│  · 持有真实实现（auth_providers 等）                    │
│  · 在 ProviderScope(overrides: [...]) 里把真实实现      │
│    注入到共享层的"占位 Provider"                        │
├──────────────────────────────────────────────────────┤
│  共享层 (core_shared package)                         │
│  · 只定义接口 + 数据模型 + "占位 Provider"              │
│  · 不依赖任何具体实现                                  │
├──────────────────────────────────────────────────────┤
│  子插件 (feature_xxx packages)                        │
│  · 只 import core_shared                              │
│  · watch/read 共享层的 Provider                        │
│  · 完全不知道主项目的存在                               │
└──────────────────────────────────────────────────────┘

第一步：共享层 ------ 定义接口和占位 Provider

// packages/core_shared/lib/models/user_info.dart

class UserInfo {
  final String uid;
  final String name;
  final String avatar;

  const UserInfo({
    required this.uid,
    required this.name,
    required this.avatar,
  });

  static const empty = UserInfo(uid: '', name: '', avatar: '');

  bool get isLoggedIn => uid.isNotEmpty;
}

// packages/core_shared/lib/providers/shared_auth_provider.dart

import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../models/user_info.dart';

/// 占位 Provider：运行时必须被主项目 override，否则直接报错。
/// 子插件只 watch 这个，不需要知道登录逻辑的实现细节。
final sharedUserProvider = Provider<UserInfo>((ref) {
  throw UnimplementedError(
    'sharedUserProvider 必须在主项目的 ProviderScope 中 override！'
    '请检查 main.dart 的 ProviderScope(overrides: [...])',
  );
});

// packages/core_shared/lib/providers/shared_cart_provider.dart

import 'package:flutter_riverpod/flutter_riverpod.dart';

/// 购物车条目数（子插件写入，主项目可以 watch）
/// 默认实现返回 0；子插件会 override 注入真实 Notifier
final sharedCartCountProvider = Provider<int>((ref) => 0);

第二步：子插件 A（个人中心） ------ 只 import 共享层

# packages/feature_profile/pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^2.6.1
  core_shared:
    path: ../core_shared     # 只依赖共享层
  # ↑ 注意：不依赖主项目，不依赖 feature_cart

// packages/feature_profile/lib/profile_page.dart

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:core_shared/providers/shared_auth_provider.dart';
import 'package:core_shared/providers/shared_cart_provider.dart';

class ProfilePage extends ConsumerWidget {
  const ProfilePage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：sharedUserProvider 或 sharedCartCountProvider 任一变化
    //    → 整个 ProfilePage.build() 重跑
    //    → CircleAvatar、用户名 Text、购物车数 Text 全部更新
    //    ⚠️ CartPage 和 MainShell 不受 ProfilePage 重建影响（各自独立 watch）
    final user = ref.watch(sharedUserProvider);
    final cartCount = ref.watch(sharedCartCountProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('个人中心（子插件A）')),
      body: Padding(
        padding: const EdgeInsets.all(24),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            CircleAvatar(
              radius: 40,
              child: Text(user.name.isNotEmpty ? user.name[0] : '?',
                  style: const TextStyle(fontSize: 32)),
            ),
            const SizedBox(height: 16),
            Text('用户名：${user.name}', style: const TextStyle(fontSize: 20)),
            Text('UID：${user.uid}'),
            const Divider(height: 32),
            Text('购物车商品数：$cartCount',
                style: const TextStyle(fontSize: 18)),
            const SizedBox(height: 12),
            const Text(
              '👆 这个数字来自 feature_cart 子插件，\n'
              '   但 profile 完全不知道 cart 的存在，\n'
              '   两个插件通过共享层的 Provider 间接通信。',
              style: TextStyle(color: Colors.grey),
            ),
          ],
        ),
      ),
    );
  }
}

第三步：子插件 B（购物车） ------ 暴露 Notifier 供主项目注入

# packages/feature_cart/pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^2.6.1
  core_shared:
    path: ../core_shared     # 只依赖共享层

// packages/feature_cart/lib/cart_notifier.dart

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:core_shared/providers/shared_auth_provider.dart';
import 'package:core_shared/models/user_info.dart';

class CartItem {
  final String id;
  final String name;
  final int quantity;

  const CartItem({required this.id, required this.name, this.quantity = 1});

  CartItem copyWith({int? quantity}) =>
      CartItem(id: id, name: name, quantity: quantity ?? this.quantity);
}

class CartNotifier extends Notifier<List<CartItem>> {
  @override
  List<CartItem> build() {
    // 购物车依赖当前用户 → watch 共享层的 user
    // 用户切换时，购物车自动清空重建
    final user = ref.watch(sharedUserProvider);
    if (!user.isLoggedIn) return [];

    // 实际项目这里可以从本地缓存加载该用户的购物车
    return [];
  }

  void addItem(String name) {
    state = [...state, CartItem(id: '${state.length + 1}', name: name)];
  }

  void removeItem(String id) {
    state = state.where((item) => item.id != id).toList();
  }

  void clear() {
    state = [];
  }
}

// 子插件内部的完整 Provider（主项目会用它来 override 共享层的计数）
final cartProvider =
    NotifierProvider<CartNotifier, List<CartItem>>(CartNotifier.new);

// packages/feature_cart/lib/cart_page.dart

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'cart_notifier.dart';

class CartPage extends ConsumerWidget {
  const CartPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：cartProvider 变化（添加/删除/清空商品）
    //    → 整个 CartPage.build() 重跑
    //    → AppBar(件数) + ListView(商品列表) 全部更新
    //    ⚠️ 同时 MainShell 的 cartCount 也会变 → MainShell 也重建（独立的 watch 链路）
    final items = ref.watch(cartProvider);

    return Scaffold(
      appBar: AppBar(
        title: Text('购物车（${items.length} 件）'),
        actions: [
          if (items.isNotEmpty)
            IconButton(
              icon: const Icon(Icons.delete_sweep),
              onPressed: () => ref.read(cartProvider.notifier).clear(),
            ),
        ],
      ),
      body: items.isEmpty
          ? const Center(child: Text('购物车是空的'))
          : ListView.builder(
              itemCount: items.length,
              itemBuilder: (_, i) => ListTile(
                title: Text(items[i].name),
                trailing: IconButton(
                  icon: const Icon(Icons.remove_circle_outline),
                  onPressed: () =>
                      ref.read(cartProvider.notifier).removeItem(items[i].id),
                ),
              ),
            ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => ref.read(cartProvider.notifier).addItem('商品 ${items.length + 1}'),
        child: const Icon(Icons.add_shopping_cart),
      ),
    );
  }
}

第四步：主项目 ------ 用 overrides 把一切串起来

// lib/auth/auth_providers.dart  （主项目内部的真实登录实现）

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:core_shared/models/user_info.dart';

class AuthNotifier extends Notifier<UserInfo> {
  @override
  UserInfo build() => UserInfo.empty;

  void login() {
    state = const UserInfo(
      uid: 'u_10086',
      name: '张三',
      avatar: 'https://example.com/avatar.png',
    );
  }

  void logout() {
    state = UserInfo.empty;
  }
}

final authProvider =
    NotifierProvider<AuthNotifier, UserInfo>(AuthNotifier.new);

// lib/main.dart  （核心：ProviderScope overrides 把所有模块连起来）

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

// 共享层
import 'package:core_shared/providers/shared_auth_provider.dart';
import 'package:core_shared/providers/shared_cart_provider.dart';

// 主项目
import 'auth/auth_providers.dart';

// 子插件
import 'package:feature_profile/profile_page.dart';
import 'package:feature_cart/cart_notifier.dart';
import 'package:feature_cart/cart_page.dart';

void main() {
  runApp(
    ProviderScope(
      overrides: [
        // ★ 关键：把共享层的"占位 Provider"指向真实实现

        // 1. 共享用户信息 ← 主项目的 authProvider
        sharedUserProvider.overrideWith((ref) {
          return ref.watch(authProvider);  // auth 变 → 共享 user 变 → 子插件自动刷新
        }),

        // 2. 共享购物车数量 ← 子插件 cart 的 cartProvider
        sharedCartCountProvider.overrideWith((ref) {
          return ref.watch(cartProvider).length;  // cart 变 → 数量变 → profile 自动刷新
        }),
      ],
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: '模块化 Riverpod Demo',
      theme: ThemeData(useMaterial3: true, colorSchemeSeed: Colors.blue),
      home: const MainShell(),
    );
  }
}

class MainShell extends ConsumerWidget {
  const MainShell({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：authProvider / cartProvider / _tabIndexProvider 任一变化
    //    → 整个 MainShell.build() 重跑
    //    → AppBar(用户名/登录按钮) + BottomNavigationBar(购物车 Badge + 选中态) 更新
    //    ⚠️ body 是 const _TabBody()，它是独立的 ConsumerWidget
    //       MainShell 重建时 Flutter 发现 _TabBody 是同一个 const 实例，跳过重建
    //       _TabBody 只在自己 watch 的 _tabIndexProvider 变化时才重建
    final user = ref.watch(authProvider);
    final cartCount = ref.watch(cartProvider).length;

    return Scaffold(
      appBar: AppBar(
        title: Text(user.isLoggedIn ? '你好, ${user.name}' : '未登录'),
        actions: [
          if (user.isLoggedIn)
            IconButton(
              icon: const Icon(Icons.logout),
              onPressed: () => ref.read(authProvider.notifier).logout(),
            )
          else
            IconButton(
              icon: const Icon(Icons.login),
              onPressed: () => ref.read(authProvider.notifier).login(),
            ),
        ],
      ),
      body: const _TabBody(),
      bottomNavigationBar: BottomNavigationBar(
        items: [
          const BottomNavigationBarItem(icon: Icon(Icons.person), label: '我的'),
          BottomNavigationBarItem(
            icon: Badge(
              label: Text('$cartCount'),
              isLabelVisible: cartCount > 0,
              child: const Icon(Icons.shopping_cart),
            ),
            label: '购物车',
          ),
        ],
        onTap: (i) => ref.read(_tabIndexProvider.notifier).state = i,
        currentIndex: ref.watch(_tabIndexProvider),
      ),
    );
  }
}

final _tabIndexProvider = StateProvider<int>((ref) => 0);

class _TabBody extends ConsumerWidget {
  const _TabBody();
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 🔄 刷新范围：_tabIndexProvider 变化（切换 tab）
    //    → _TabBody.build() 重跑 → 切换显示 ProfilePage 或 CartPage
    //    ⚠️ authProvider / cartProvider 变化不影响 _TabBody（它不 watch 它们）
    //       但 ProfilePage / CartPage 各自有自己的 watch，会独立刷新
    return switch (ref.watch(_tabIndexProvider)) {
      0 => const ProfilePage(),  // 子插件 A
      1 => const CartPage(),     // 子插件 B
      _ => const SizedBox(),
    };
  }
}

数据流全景图

┌─ 主项目 ──────────────────────────────────────────────────────────────┐
│                                                                       │
│  authProvider (AuthNotifier)                                          │
│       │                                                               │
│       │  override                                                     │
│       ▼                                                               │
│  ┌─ 共享层 ──────────────────────────────────────────────────────┐    │
│  │  sharedUserProvider ◄──── watch ──── CartNotifier.build()     │    │
│  │                                      (用户切换→购物车清空)     │    │
│  │  sharedCartCountProvider ◄── override ── cartProvider.length  │    │
│  └───────────────────────────────────────────────────────────────┘    │
│       │                    │                                          │
│       │ watch              │ watch                                    │
│       ▼                    ▼                                          │
│  ProfilePage          CartPage                                        │
│  (子插件A)            (子插件B)                                       │
│  显示用户名+购物车数   添加/删除商品                                   │
└───────────────────────────────────────────────────────────────────────┘

学到什么

要点	说明
共享层只放接口	core_shared 只有数据模型 + 占位 Provider，不含任何业务逻辑实现
占位 Provider 抛异常	忘了 override 会立即报错，不会悄悄返回错误数据
overrideWith 建立桥梁	主项目在 ProviderScope 把真实实现注入占位 Provider
子插件互不 import	profile 不 import cart，cart 不 import profile，但通过共享层间接通信
依赖方向清晰	子插件 → 共享层 ← 主项目；箭头永远指向共享层，不会交叉
用户切换自动连锁	auth 变 → sharedUser 变 → CartNotifier.build 重跑 → 购物车清空 → 数量归零 → profile 页刷新

踩坑点

// ❌ 子插件直接 import 主项目代码 → 循环依赖，无法独立编译
import 'package:my_app/auth/auth_providers.dart'; // 千万别这样

// ✅ 子插件只 import core_shared
import 'package:core_shared/providers/shared_auth_provider.dart';

// ❌ 忘了在 ProviderScope 写 override → 运行时 UnimplementedError 崩溃
ProviderScope(
  overrides: [], // 漏了！
  child: MyApp(),
)

// ✅ 占位 Provider 的报错信息会明确告诉你漏了什么

// ❌ override 里用 read 代替 watch → 后续变化不同步
sharedUserProvider.overrideWith((ref) {
  return ref.read(authProvider); // 只读一次，用户登出后 profile 不会更新！
}),

// ✅ override 里用 watch → 源头变化自动传播到所有下游
sharedUserProvider.overrideWith((ref) {
  return ref.watch(authProvider); // auth 变 → sharedUser 变 → 全链路刷新
}),

---

Riverpod 3 迁移速查（影响线上行为的 5 条）

如果你的项目要升级到 Riverpod 3.0，以下是会改变运行时行为的变更：

变更	影响	应对
自动重试	失败的 Provider 默认自动重试	非幂等操作需要显式 retry: (...) => null
不可见时暂停	页面不可见时 watch 暂停	需要后台持续监听的场景用 TickerMode(enabled: true) 包裹
统一用 == 过滤	相等的新值不再触发更新	Stream 场景需注意；可 override updateShouldNotify
异常包装	catch 拿到的是 ProviderException	需要 e.exception is XxxError 二次拆包
Legacy import	StateProvider 等移到 legacy.dart	新代码用 Notifier，旧代码改 import 路径

---

总结：一张表选 Provider 类型

你的需求	用什么	场景参照
一个开关/枚举	StateProvider	场景 1
有方法的同步状态	Notifier + NotifierProvider	场景 2
异步只读数据	FutureProvider	场景 3
按参数缓存	.family	场景 4
页面级临时状态	.autoDispose	场景 4
有方法的异步状态	AsyncNotifier	场景 5
多步数据管道	多个 Provider 链式 watch	场景 6
只读派生计算	Provider watch 上游	场景 2 (completedCount)
实时数据流	StreamProvider.autoDispose + ref.onDispose	场景 7
主项目与子插件状态同步	共享层占位 Provider + overrideWith	场景 9

---

附录：9 个场景的刷新范围总览

一句话原则

ref.watch 写在哪个 Widget 的 build 里，那个 Widget 就是刷新边界。

Provider 变化只会重建 watch 了它的 ConsumerWidget / ConsumerStatefulWidget，不会波及其他。

全景对照表

场景1  isDarkModeProvider 变化
       └─🔄 ThemePage.build()          ← 整个页面重建（Switch + Text）

场景2  todoListProvider 变化
       └─🔄 TodoPage.build()           ← AppBar(计数) + ListView(所有 ListTile) 重建
          └─ completedCountProvider     ← 派生 Provider 跟着自动重算

场景3  userListProvider 状态切换 (loading ↔ data ↔ error)
       └─🔄 UserListPage.build()       ← body 区域三态切换

场景4  userDetailProvider(userId) 状态切换
       └─🔄 UserDetailPage.build()     ← 仅该 userId 的详情页重建
          ⚠️ 其他 userId 的页面不受影响  ← family 的隔离作用

场景5  authProvider 变化 (未登录 → loading → 已登录)
       ├─🔄 _LoginPageState.build()    ← ElevatedButton 切换 loading/可点击
       │  └─ ref.listen → 回调         ← ⚠️ 不触发 build，只执行跳转/SnackBar
       └─🔄 HomePage.build()           ← AppBar 用户名更新

场景6  searchResultsProvider 变化 (防抖 → 请求 → 结果)
       └─🔄 SearchPage.build()         ← Expanded 区域切换
          ⚠️ TextField 不受影响         ← 它通过 ref.read 写入，不 watch

场景7  liveEventProvider (stream 每 2s 推送)
       └─🔄 _LiveEventPageState.build()← Container(状态) + ListView(历史) 更新
          └─ ref.listen + setState      ← 与 watch 合并为同一帧，不双重渲染

场景9  authProvider 变化 (登录/登出)
       ├─🔄 MainShell.build()          ← AppBar(用户名) + BottomNav 更新
       │  └─ const _TabBody()          ← ⚠️ 不被 MainShell 重建波及（const 复用）
       ├─ override 链: auth → sharedUser → CartNotifier.build()
       │  └─🔄 CartPage.build()        ← 购物车清空，列表重建
       │  └─ override 链: cart.length → sharedCartCount
       │     └─🔄 ProfilePage.build()  ← 购物车数字归零
       └─🔄 _TabBody.build()           ← 仅在 _tabIndexProvider 变化时重建

       cartProvider 变化 (添加商品)
       ├─🔄 CartPage.build()           ← 列表更新
       ├─🔄 MainShell.build()          ← Badge 数字更新
       └─🔄 ProfilePage.build()        ← 购物车数字更新
          ⚠️ _TabBody 不受影响          ← 它不 watch cartProvider

如何缩小刷新范围（进阶技巧）

上面每个场景中，ref.watch 都写在 Widget 的 build 最顶层 ，所以整个 build 树都会重建。

实际项目中可以用以下手段 缩小刷新范围。

先理解一个前提 ：build() 重跑 ≠ 整个页面像素级重绘。Flutter 渲染分三层：
Widget 树 （build 产出）→ Element 树 （框架做新旧 diff）→ RenderObject 树 （真正布局和绘制像素）。
const Widget 在 diff 时直接跳过；只有真正内容变了的 RenderObject 才会重新 layout/paint。

所以 build 本身是轻量的，真正昂贵的是 layout 和 paint 。

下面的技巧目标是：连 build 的调用范围也收窄到最小。

---

技巧 1：Consumer 局部包裹 ------ 最常用，改造成本最低

场景：一个商品详情页，只有底部的「购物车数量」需要实时更新，其他部分（图片、标题、描述）都是静态的。

// product_detail_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

// 假设已有
final cartProvider = StateProvider<int>((ref) => 0);

// ⚠️ 注意：外层是普通 StatelessWidget，不是 ConsumerWidget
//    → 它自己永远不会因为 Provider 变化而重建
class ProductDetailPage extends StatelessWidget {
  const ProductDetailPage({super.key});

  @override
  Widget build(BuildContext context) {
    print('ProductDetailPage.build()'); // 只在首次进入时打印一次

    return Scaffold(
      appBar: AppBar(title: const Text('AirPods Pro')),
      body: Column(
        children: [
          // ────── 这些全是静态内容，永远不重建 ──────
          const SizedBox(
            height: 200,
            child: Placeholder(), // 模拟商品图片
          ),
          const Padding(
            padding: EdgeInsets.all(16),
            child: Text(
              'Apple AirPods Pro 第二代',
              style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
            ),
          ),
          const Padding(
            padding: EdgeInsets.symmetric(horizontal: 16),
            child: Text('主动降噪 · 自适应通透模式 · 个性化空间音频'),
          ),
          const Divider(height: 32),

          // ────── 只有这一小块会因为 cartProvider 变化而重建 ──────
          Consumer(
            builder: (context, ref, child) {
              print('  Consumer.build()'); // 每次 cart 变化都打印
              // 🔄 刷新范围：仅此 Consumer 内部的 Row
              final count = ref.watch(cartProvider);
              return Padding(
                padding: const EdgeInsets.symmetric(horizontal: 16),
                child: Row(
                  mainAxisAlignment: MainAxisAlignment.spaceBetween,
                  children: [
                    Text('购物车: $count 件',
                        style: const TextStyle(fontSize: 18)),
                    FilledButton.icon(
                      onPressed: () =>
                          ref.read(cartProvider.notifier).state++,
                      icon: const Icon(Icons.add_shopping_cart),
                      label: const Text('加入购物车'),
                    ),
                  ],
                ),
              );
            },
          ),

          // ────── 这下面也是静态内容，永远不重建 ──────
          const SizedBox(height: 20),
          const Padding(
            padding: EdgeInsets.all(16),
            child: Text('商品详情介绍...（很长的文字）'),
          ),
        ],
      ),
    );
  }
}

刷新范围图：

ProductDetailPage (StatelessWidget)          ← 永远不重建
├── AppBar                                   ← 永远不重建
├── 商品图片 (const)                          ← 永远不重建
├── 商品标题 (const)                          ← 永远不重建
├── 商品描述 (const)                          ← 永远不重建
├── Consumer                                 ← 🔄 仅此块重建
│   └── Row: "购物车: N 件" + 按钮            ← 🔄 count 变了才更新
├── 商品详情 (const)                          ← 永远不重建

学到什么：

• 外层用 StatelessWidget 而不是 ConsumerWidget → 整个页面骨架永远不参与刷新
• Consumer 是一个普通 Widget，可以塞在树的任意位置，不需要重构整个页面
• 点击「加入购物车」→ cartProvider 变化 → 只有 Consumer 内部的 Row 重建，图片/标题/描述纹丝不动

---

技巧 2：select 精确订阅某个字段 ------ 大对象只关心一部分时

场景：用户资料有很多字段（头像、昵称、签名、积分、等级...），但某个 Widget 只显示昵称。

// user_profile_provider.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';

class UserProfile {
  final String name;
  final String avatar;
  final String bio;
  final int points;
  final int level;

  const UserProfile({
    required this.name,
    required this.avatar,
    required this.bio,
    required this.points,
    required this.level,
  });
}

class UserProfileNotifier extends Notifier<UserProfile> {
  @override
  UserProfile build() => const UserProfile(
        name: '张三',
        avatar: 'https://example.com/avatar.png',
        bio: 'Flutter 开发者',
        points: 1000,
        level: 5,
      );

  void addPoints(int p) {
    state = UserProfile(
      name: state.name,
      avatar: state.avatar,
      bio: state.bio,
      points: state.points + p,
      level: state.level,
    );
  }

  void updateName(String name) {
    state = UserProfile(
      name: name,
      avatar: state.avatar,
      bio: state.bio,
      points: state.points,
      level: state.level,
    );
  }
}

final userProfileProvider =
    NotifierProvider<UserProfileNotifier, UserProfile>(UserProfileNotifier.new);

// select_demo_page.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'user_profile_provider.dart';

class SelectDemoPage extends ConsumerWidget {
  const SelectDemoPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // ❌ 不用 select：user 的任何字段变化（积分、等级...）都会让这里重建
    // final user = ref.watch(userProfileProvider);

    // ✅ 用 select：只订阅 name 字段
    //    积分变了？不重建。等级变了？不重建。只有 name 变了才重建
    // 🔄 刷新范围：仅当 name 字段的 == 比较结果变化时，才重建 SelectDemoPage
    final name = ref.watch(
      userProfileProvider.select((profile) => profile.name),
    );

    print('SelectDemoPage.build() - name=$name');

    return Scaffold(
      appBar: AppBar(title: Text('你好, $name')),
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Text('当前用户: $name', style: const TextStyle(fontSize: 24)),
            const SizedBox(height: 24),
            // 点这个按钮 → 积分变了 → 但 name 没变 → SelectDemoPage 不重建
            ElevatedButton(
              onPressed: () =>
                  ref.read(userProfileProvider.notifier).addPoints(100),
              child: const Text('加 100 积分（不触发本页重建）'),
            ),
            const SizedBox(height: 12),
            // 点这个按钮 → name 变了 → SelectDemoPage 重建
            ElevatedButton(
              onPressed: () =>
                  ref.read(userProfileProvider.notifier).updateName('李四'),
              child: const Text('改名为李四（触发本页重建）'),
            ),
            const SizedBox(height: 32),
            // 用另一个 Consumer + select 单独显示积分
            Consumer(
              builder: (context, ref, _) {
                // 🔄 刷新范围：仅当 points 变化时，这个 Consumer 重建
                final points = ref.watch(
                  userProfileProvider.select((p) => p.points),
                );
                print('  Points Consumer.build() - points=$points');
                return Text('积分: $points', style: const TextStyle(fontSize: 20));
              },
            ),
          ],
        ),
      ),
    );
  }
}

刷新范围图：

用户点击「加 100 积分」→ userProfileProvider 变化（points 字段改了）

SelectDemoPage (select: name)                ← ⚠️ 不重建！name 没变
├── AppBar(title: '你好, 张三')               ← ⚠️ 不重建
├── Text('当前用户: 张三')                     ← ⚠️ 不重建
├── ElevatedButton('加积分')                  ← ⚠️ 不重建
├── ElevatedButton('改名')                    ← ⚠️ 不重建
└── Consumer (select: points)                ← 🔄 重建！points 变了
    └── Text('积分: 1100')                    ← 🔄 更新数字

用户点击「改名为李四」→ userProfileProvider 变化（name 字段改了）

SelectDemoPage (select: name)                ← 🔄 重建！name 变了
├── AppBar(title: '你好, 李四')               ← 🔄 更新
├── Text('当前用户: 李四')                     ← 🔄 更新
└── Consumer (select: points)                ← ⚠️ 不重建！points 没变

学到什么：

• select 用 == 对比投影结果，相等就跳过 → 精确到字段级别的刷新控制
• 同一个 Provider 可以在不同位置用不同 select，各自只关心自己要的字段
• 特别适合大 Model 对象（User、Order、Settings...），避免无关字段变化导致的连锁重建

---

技巧 3：拆分成多个小 ConsumerWidget ------ 中大型页面的标准做法

场景：把场景 2 的待办清单拆分，让「AppBar 计数」和「列表内容」各自独立刷新。

// todo_page_optimized.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'todo_notifier.dart';

// ⚠️ 主页面是普通 StatelessWidget，不参与任何 Provider 刷新
class TodoPageOptimized extends StatelessWidget {
  const TodoPageOptimized({super.key});

  @override
  Widget build(BuildContext context) {
    print('TodoPageOptimized.build()'); // 只在首次时打印一次
    return Scaffold(
      appBar: AppBar(
        title: const _TodoAppBarTitle(), // 独立 ConsumerWidget
      ),
      body: const _TodoListBody(),       // 独立 ConsumerWidget
      floatingActionButton: FloatingActionButton(
        onPressed: () => _showAddDialog(context),
        child: const Icon(Icons.add),
      ),
    );
  }

  void _showAddDialog(BuildContext context) {
    final controller = TextEditingController();
    showDialog(
      context: context,
      builder: (_) => Consumer(
        builder: (context, ref, _) => AlertDialog(
          title: const Text('添加待办'),
          content: TextField(controller: controller, autofocus: true),
          actions: [
            TextButton(
              onPressed: () {
                if (controller.text.isNotEmpty) {
                  ref.read(todoListProvider.notifier).add(controller.text);
                }
                Navigator.pop(context);
              },
              child: const Text('确定'),
            ),
          ],
        ),
      ),
    );
  }
}

// ────── 拆出来的小组件 1：AppBar 标题 ──────
class _TodoAppBarTitle extends ConsumerWidget {
  const _TodoAppBarTitle();

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    print('  _TodoAppBarTitle.build()');
    // 🔄 刷新范围：仅此 Widget
    //    用 select 只订阅 length 和完成数，列表内容变化但数量不变时不重建
    final total = ref.watch(todoListProvider.select((list) => list.length));
    final done = ref.watch(completedCountProvider);
    return Text('待办 (已完成 $done/$total)');
  }
}

// ────── 拆出来的小组件 2：列表 ──────
class _TodoListBody extends ConsumerWidget {
  const _TodoListBody();

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    print('  _TodoListBody.build()');
    // 🔄 刷新范围：仅此 Widget
    //    列表数据变化时只重建列表，不影响 AppBar
    final todos = ref.watch(todoListProvider);
    return ListView.builder(
      itemCount: todos.length,
      itemBuilder: (_, i) {
        final todo = todos[i];
        return ListTile(
          leading: Checkbox(
            value: todo.completed,
            onChanged: (_) =>
                ref.read(todoListProvider.notifier).toggle(todo.id),
          ),
          title: Text(
            todo.title,
            style: TextStyle(
              decoration: todo.completed ? TextDecoration.lineThrough : null,
            ),
          ),
          trailing: IconButton(
            icon: const Icon(Icons.delete),
            onPressed: () =>
                ref.read(todoListProvider.notifier).remove(todo.id),
          ),
        );
      },
    );
  }
}

刷新范围对比（优化前 vs 优化后）：

优化前（场景 2 原始写法）：
  todoListProvider 变化
  └─🔄 TodoPage.build()               ← 整页重建（AppBar + ListView + FAB 全跑一遍）

优化后（拆分写法）：
  勾选一个待办（toggle）→ todoListProvider 变化
  ├─ TodoPageOptimized.build()         ← ⚠️ 不重建（StatelessWidget，没 watch）
  ├─🔄 _TodoAppBarTitle.build()        ← 🔄 重建（completedCount 变了）
  ├─🔄 _TodoListBody.build()           ← 🔄 重建（列表内容变了）
  └─ FloatingActionButton              ← ⚠️ 不重建（const Icon）

  添加一个待办 → todoListProvider 变化，但没有新完成的
  ├─ TodoPageOptimized.build()         ← ⚠️ 不重建
  ├─🔄 _TodoAppBarTitle.build()        ← 🔄 重建（total 从 2 变 3）
  ├─🔄 _TodoListBody.build()           ← 🔄 重建（列表多了一条）
  └─ FloatingActionButton              ← ⚠️ 不重建

学到什么：

• 把一个大 ConsumerWidget 拆成 外壳 StatelessWidget + 多个小 ConsumerWidget
• 每个小组件只 watch 自己关心的数据 → 不相关的变化不会波及
• 配合 select 还能进一步收窄（比如 _TodoAppBarTitle 只 select length）
• 这是中大型项目的标准做法，不是过度优化

---

三种技巧选择指南

情况	推荐技巧	改造成本
页面大部分是静态的，只有一小块需要动态数据	Consumer 局部包裹	最低，加 3 行代码
一个大对象（User/Order），但只用其中 1-2 个字段	select 精确订阅	低，改一行 watch
页面复杂、多个区域依赖不同 Provider	拆分小 ConsumerWidget	中等，需要提取组件
以上组合	Consumer + select + 拆 Widget 混用	视情况而定

总结 ：场景 1-9 的示例为了教学清晰，用整个 ConsumerWidget 做页面。

生产项目中应该按上面的技巧 把刷新范围收窄到真正需要更新的部分 。
build() 重跑不等于像素重绘（Flutter 框架会 diff），但收窄 build 范围仍然是好习惯------

减少不必要的 Widget 实例创建、diff 对比和 GC 压力，尤其在列表页和复杂表单页效果明显。