riverpod-3-0-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Riverpod — Migrating from 2.0 to 3.0

Riverpod — 从2.0迁移至3.0

For a full list of changes and highlights, see the official Riverpod docs (What's new in Riverpod 3.0). This skill summarizes the main migration steps.

如需完整的变更列表和亮点，请查看Riverpod官方文档（What's new in Riverpod 3.0）。本技能总结了主要的迁移步骤。

Automatic retry

自动重试

Failing providers are retried by default in 3.0. To disable globally:

dart

ProviderScope(retry: (retryCount, error) => null, child: MyApp())
// or ProviderContainer(retry: (retryCount, error) => null)

To disable per provider, pass retry: (retryCount, error) => null when defining the provider (or

@Riverpod(retry: ...)

with codegen). See riverpod-retry.

在3.0版本中，失败的Provider默认会自动重试。如需全局禁用：

dart

ProviderScope(retry: (retryCount, error) => null, child: MyApp())
// or ProviderContainer(retry: (retryCount, error) => null)

如需针对单个Provider禁用，在定义Provider时传入retry: (retryCount, error) => null（使用代码生成时则为

@Riverpod(retry: ...)

）。详情请查看riverpod-retry。

Out-of-view providers are paused

不可见Provider会被暂停

Listeners in widgets that are not visible (e.g. off-screen) are paused by default. There is no global switch. To keep a subtree from pausing, wrap it in TickerMode(enabled: true, child: ...) so the Consumer(s) inside do not follow the pause behavior.

位于不可见组件（例如屏幕外）中的监听器默认会被暂停。目前没有全局开关。如需阻止某个子树被暂停，可将其包裹在**TickerMode(enabled: true, child: ...)**中，这样内部的Consumer就不会遵循暂停行为。

Legacy providers (StateProvider, StateNotifierProvider, ChangeNotifierProvider)

遗留Provider（StateProvider、StateNotifierProvider、ChangeNotifierProvider）

These are moved to a legacy import. They are not removed but discouraged. To keep using them:

dart

import 'package:flutter_riverpod/legacy.dart';
// or hooks_riverpod/legacy.dart, riverpod/legacy.dart

这些Provider被移至遗留导入路径。它们并未被移除，但官方不推荐使用。如需继续使用：

dart

import 'package:flutter_riverpod/legacy.dart';
// 或 hooks_riverpod/legacy.dart、riverpod/legacy.dart

Updates use ==

更新使用==比较

All providers now use == to filter updates (no longer identical). StreamProvider / StreamNotifier values are compared with ==. To customize, override updateShouldNotify(previous, next) on the Notifier (e.g. return true to always notify).

所有Provider现在使用**==来过滤更新（不再使用identical**）。StreamProvider / StreamNotifier的值也会通过==进行比较。如需自定义比较逻辑，可在Notifier上重写**updateShouldNotify(previous, next)**方法（例如返回true以始终触发通知）。

ProviderObserver API change

ProviderObserver API变更

Observer methods now receive a single ProviderObserverContext (with container, provider, and optional mutation) instead of separate (provider, value, container) parameters. Update signatures, e.g.:

didAddProvider(ProviderObserverContext context, Object? value) (and similar for other callbacks).

观察者方法现在接收单个ProviderObserverContext参数（包含container、provider和可选的mutation），而非之前的多个独立参数（provider、value、container）。请更新方法签名，例如：

didAddProvider(ProviderObserverContext context, Object? value)（其他回调方法类似）。

Ref simplified; Ref subclasses removed

Ref简化；移除Ref子类

Ref no longer has a type parameter. Use Ref everywhere (e.g. replace MyProviderRef with Ref in codegen).
ProviderRef.state, Ref.listenSelf, FutureProviderRef.future are moved onto Notifier/AsyncNotifier: use Notifier.state, Notifier.listenSelf, AsyncNotifier.future instead of on ref. If you need these, use a class-based Notifier/AsyncNotifier and call them on the notifier.

Ref不再带有类型参数。请在所有场景使用Ref（例如在代码生成中将MyProviderRef替换为Ref）。
ProviderRef.state、Ref.listenSelf、FutureProviderRef.future已移至Notifier/AsyncNotifier：请使用Notifier.state、Notifier.listenSelf、AsyncNotifier.future替代Ref上的对应属性。如果需要这些功能，请使用基于类的Notifier/AsyncNotifier并在Notifier实例上调用它们。

AutoDispose type names removed

移除AutoDispose类型名称

AutoDispose is still supported, but the separate type names (e.g. AutoDisposeProvider, AutoDisposeNotifier) are unified. Use Provider, Notifier, etc. with the same behavior. Migration: case-sensitive replace AutoDispose with a space (empty string) in type names.

AutoDispose仍然受支持，但独立的类型名称（例如AutoDisposeProvider、AutoDisposeNotifier）已被统一。请使用Provider、Notifier等类型，它们的行为保持不变。迁移方式：在类型名称中区分大小写地将AutoDispose替换为空字符串。

Family Notifier types removed

移除Family Notifier类型

FamilyNotifier, FamilyAsyncNotifier, FamilyStreamNotifier are removed. Use Notifier / AsyncNotifier / StreamNotifier and pass the parameter via the constructor (and store it in a field). Remove the parameter from build; build() takes no family argument. Example:

Before:

FamilyNotifier<int, String>

with

int build(String arg)

After:

Notifier<int>

with constructor

MyNotifier(this.arg)

and

final String arg;

, and int build() using arg.

FamilyNotifier、FamilyAsyncNotifier、FamilyStreamNotifier已被移除。请使用Notifier / AsyncNotifier / StreamNotifier，并通过构造函数传入参数（并将其存储为字段）。请从build方法中移除参数；**build()**不再接收family参数。示例：

之前：

FamilyNotifier<int, String>

，包含

int build(String arg)

方法。

之后：
```
Notifier<int>
```
，包含构造函数
```
MyNotifier(this.arg)
```
和
```
final String arg;
```
字段，以及使用arg的**int build()**方法。

ProviderException

When a provider throws, the exception is wrapped in ProviderException. If you catch the original type (e.g. on NotFoundException), change to on ProviderException catch (e) and check e.exception is NotFoundException. If you only use AsyncValue and value.hasError / value.error, no change needed.

当Provider抛出异常时，该异常会被包装在ProviderException中。如果您之前捕获原始异常类型（例如on NotFoundException），请改为on ProviderException catch (e)并检查e.exception is NotFoundException。如果您仅使用AsyncValue和value.hasError / value.error，则无需修改。

Summary

总结

Retry: disable via retry on scope/container or provider.
Pause: use TickerMode(enabled: true) where you don’t want pausing.
Legacy: use flutter_riverpod/legacy.dart (or equivalent) for StateProvider / StateNotifierProvider / ChangeNotifierProvider.
Ref: use plain Ref; move state / listenSelf / future to Notifier/AsyncNotifier.
AutoDispose: remove “AutoDispose” from type names.
Family notifiers: use Notifier/AsyncNotifier with constructor argument; build() has no parameter.
Errors: catch ProviderException and inspect exception when you need the original type.

For version highlights and more detail, see the official Riverpod documentation.

重试：通过scope/container或Provider上的retry参数禁用。
暂停：在无需暂停的区域使用TickerMode(enabled: true)。
遗留Provider：使用flutter_riverpod/legacy.dart（或等价导入）来使用StateProvider / StateNotifierProvider / ChangeNotifierProvider。
Ref：使用普通的Ref；将state / listenSelf / future移至Notifier/AsyncNotifier。
AutoDispose：从类型名称中移除“AutoDispose”。
Family Notifier：使用带构造函数参数的Notifier/AsyncNotifier；**build()**无参数。
错误处理：捕获ProviderException并在需要原始类型时检查exception属性。

如需版本亮点和更多细节，请查看Riverpod官方文档。