---
title: "Riverpodとは？Flutterの状態管理をRiverpod 3系で始める導入・使い方・移行ガイド"
url: "https://www.issoh.co.jp/tech/details/9959/"
published: 2025-11-25
updated: 2026-10-26
categories: ["Flutter"]
publisher: "株式会社一創"
---

# Riverpodとは？Flutterの状態管理をRiverpod 3系で始める導入・使い方・移行ガイド

Riverpodは、Flutterアプリの状態をウィジェットツリーの外側で保持し、必要な画面だけを再描画させるためのライブラリです。2025年9月10日に3.0.0が安定版になり、2026年10月時点の最新は3.4.3。`StateNotifierProvider`や`StateProvider`が通常のimportから外れ、コード生成の書き方も変わったため、2.x時代の解説記事をそのまま写すとコンパイルが通りません。

この記事では、3系で動く最小構成、Providerの種類と3系での扱い、非同期データや引数付きProviderの書き方、2.xから移行するときに壊れる箇所を、配布パッケージのソースと公式ドキュメントで確認しました。挙動の数字は、Dart SDK 3.13.5とriverpod 3.4.3でコードを実行して得た値です。

## まとめ：Riverpod 3系を導入する前に押さえる前提

| 論点                    | 2026年10月時点の結論                                 |
| --------------------- | --------------------------------------------- |
| 入れるパッケージ              | Flutterアプリは flutter\_riverpod 3.4.3 の1本       |
| 必要なSDK                | Dart 3.12以上＝Flutter 3.44.0以降                  |
| コード生成                 | riverpod\_generator 4.0.9＋build\_runner 2.16系 |
| 新規に使うProvider         | Notifier系とFuture/Stream系                      |
| StateNotifierProvider | legacy.dart からのimportで継続利用は可能                 |
| 永続化・Mutation          | experimental配下。マイナー版でも壊れうる                    |

導入前に確認するのはSDK要件とbuild\_runnerの版の2点です。Flutter 3.41系のまま`flutter_riverpod: ^3.0.0`のような幅のある指定で`flutter pub get`を叩くと、エラーを出さずに1世代前の3.3.2で解決され、新しいAPIだけが見つからない状態になります。また2026年10月14日に出たbuild\_runner 2.17.1は、riverpod\_generator 4.0.9と同時に入りません。

## Riverpodが引き受ける役割とProviderScopeの位置づけ

Riverpodは[公式サイト](https://riverpod.dev/)で「リアクティブ・キャッシングとデータバインディング・フレームワーク」と名乗っています。単なる値の置き場ではなく、依存の注入、非同期結果のキャッシュ、再計算のトリガー管理をまとめて引き受ける設計です。

たとえばAPIから取得したユーザー情報をProviderに入れると、その値を`ref.watch`しているウィジェットだけが再描画されます。同じコンテナ内では状態が共有されるため、画面をまたいでも取得済みの結果をそのまま読めます（再計算や再試行が走れば通信は発生します）。使われなくなったProviderの破棄は、リスナーがゼロになってから1フレーム待ち、その時点でも使われていなければ実行される仕組みです。この自動破棄はコード生成なら既定で有効で、手書きのProviderでは`isAutoDispose: true`を渡して有効にします。

実行時の前提は1つだけで、アプリ全体を`ProviderScope`で包むことです。包み忘れると`No ProviderScope found`という`StateError`が投げられます。Providerの値を保持しているのはこのウィジェットが内部に持つ`ProviderContainer`で、テストではウィジェットを介さず`ProviderContainer.test()`で直接組み立てられます。

なお、BlocやProviderパッケージ、GetXとの比較検討は[Riverpodと他の状態管理の違い](/tech/details/7039/)で扱っています。ここでは選定を終えた前提で、3系の実装に絞ります。

## Riverpod 3系のパッケージ構成とSDK要件（2026年10月時点）

[pub.dev](https://pub.dev/packages/flutter%5Friverpod)のAPIで2026年10月26日に確認した現行バージョンは次のとおりです。Riverpod系の7パッケージは2026年9月4日（日本時間）に同時公開されたまま据え置かれています。

| パッケージ                | 最新版   | 必要なDart SDK | 用途                              |
| -------------------- | ----- | ----------- | ------------------------------- |
| flutter\_riverpod    | 3.4.3 | ^3.12.0     | Flutterアプリ本体                    |
| riverpod             | 3.4.3 | ^3.12.0     | Dart単体・サーバー側                    |
| hooks\_riverpod      | 3.4.3 | ^3.12.0     | flutter\_hooks併用時               |
| riverpod\_annotation | 4.0.7 | ^3.12.0     | @riverpod の注釈                   |
| riverpod\_generator  | 4.0.9 | ^3.12.0     | build\_runner用の生成器              |
| riverpod\_lint       | 3.1.9 | \>=3.13.0-0 | analysis\_server\_plugin方式のlint |
| riverpod\_sqflite    | 0.4.7 | ^3.12.0     | 永続化（実験的）                        |

Flutterアプリなら`flutter_riverpod`だけを入れます。`riverpod`は内部で依存されるので、pubspecに両方書く必要はありません。むしろ`flutter_riverpod`しか書いていないプロジェクトで`package:riverpod/...`をimportすると、flutter\_lints既定の`depend_on_referenced_packages`に引っかかります。

要注意なのがSDKの下限です。flutter\_riverpodの`environment.sdk`は3.3.2では`^3.7.0`でしたが、3.4.1以降は`^3.12.0`に上がりました。Dart 3.12.0を同梱する最も古いFlutter安定版はFlutter 3.44.0（2026年5月18日リリース）なので、3.4系を使う条件は実質的に**Flutter 3.44.0以降**になります。

さらにriverpod\_lint 3.1.9はDart 3.13.0以上を要求します。Dart 3.13.0の同梱はFlutter 3.47.0（2026年8月12日）からなので、lintまで最新に揃えるならFlutter側も3.47系が必要です。現行の安定版は3.47.8（2026年10月23日、Dart 3.13.7）で、3.47系の変更点は[Flutter 3.47の変更点と修正履歴](/tech/details/16894/)にまとめています。

## 導入手順：pubspecからProviderScope、最初のProviderまで

依存関係はコード生成を使う前提で次のように書きます。生成器はdev\_dependenciesに置きます。以降のコードは、`main`と`MyApp`を`lib/main.dart`に、Providerの定義と`Home`を`lib/counter.dart`に置き、`main.dart`から`counter.dart`をimportする配置を想定しています。`counter.g.dart`は`dart run build_runner build`で生成され、アプリは`flutter run`で起動します。

```
environment:
  sdk: ^3.12.0

dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^3.4.3
  riverpod_annotation: ^4.0.7

dev_dependencies:
  build_runner: ^2.16.1
  riverpod_generator: ^4.0.9
```

build\_runnerを`^2.17.1`にすると解決が止まります。2.17.1は`build` 5.0.0を要求し、riverpod\_generator 4.0.9は`build`を5.0.0未満に制限しているためで、手元では次のメッセージが出ました。

```
Because riverpod_generator >=3.0.0 depends on build >=3.0.0 <5.0.0 and build_runner >=2.17.1 depends on build >=5.0.0 <5.1.0, riverpod_generator >=3.0.0 is incompatible with build_runner >=2.17.1.
```

上の`^2.16.1`のままなら2.16.2で解決されます（2.17.0は依存先の`build` 4.1.0が取り下げ扱いのため選ばれません）。`dart pub upgrade --major-versions`でbuild\_runnerだけ上げるとこの衝突に当たるので、riverpod\_generator側が`build` 5に対応するまでは2.16系に留めます。経緯は[build\_runnerのCHANGELOG](https://pub.dev/packages/build%5Frunner/changelog)の2.17.1の項に書かれています。

次に、`runApp`に渡すウィジェットを`ProviderScope`で包みます。この外側でProviderを参照すると例外になるため、先に配置しておきます。

```
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 const MaterialApp(home: Home());
  }
}
```

あとはProviderを定義して`ref.watch`で読むだけです。読み出し側の`ref`は`ConsumerWidget.build`の第2引数から受け取ります。既存の`StatefulWidget`を置き換える場合は`ConsumerStatefulWidget`と`ConsumerState`を使い、`ConsumerState`の中では`ref`がフィールドとして生えているためbuild以外のメソッドからも触れます。

`ref.watch`と`ref.read`の使い分けは3系でも変わりません。build内で値を購読するときは`ref.watch`、ボタン押下などのイベントハンドラ内で1回だけ読むときは`ref.read`です。購読はbuildのたびに作り直される仕組みなので、コールバックから`ref.watch`を呼んでも意図した再描画にはつながりません。

静的解析を効かせるなら`riverpod_lint`を入れます。3系のriverpod\_lintはcustom\_lintではなくanalysis\_server\_pluginを使う方式に変わり、`analysis_options.yaml`に`plugins:`として書いて`dart analyze`で結果を見ます。`ProviderScope`の付け忘れを指摘する`missing_provider_scope`や、関数プロバイダの第1引数が`Ref`かを見る`functional_ref`など、この記事で触れる落とし穴の多くはここで機械的に拾えます。

## Providerの種類と3系での位置づけ

2.x時代の入門記事は、Provider・StateProvider・StateNotifierProvider・ChangeNotifierProviderを同列に並べています。3系ではこのうち3つが`legacy.dart`へ移りました。riverpod 3.4.3の`lib/riverpod.dart`と`lib/legacy.dart`の公開一覧から整理すると次のとおりです。

| Provider               | 3系での扱い                          | 向いている状態                |
| ---------------------- | ------------------------------- | ---------------------- |
| Provider               | 通常のimport                       | 計算結果・依存の注入             |
| FutureProvider         | 通常のimport                       | 1回の非同期取得               |
| StreamProvider         | 通常のimport                       | WebSocket・Firestoreの購読 |
| NotifierProvider       | 通常のimport                       | メソッドで変更する同期の状態         |
| AsyncNotifierProvider  | 通常のimport                       | 取得と更新を持つ非同期の状態         |
| StreamNotifierProvider | 通常のimport                       | 購読と更新を持つ状態             |
| StateProvider          | legacy.dart                     | 既存コードの維持のみ             |
| StateNotifierProvider  | legacy.dart                     | 既存コードの維持のみ             |
| ChangeNotifierProvider | flutter\_riverpodのlegacy.dartのみ | 既存コードの維持のみ             |

コード生成を使うと、このProvider名を自分で選ぶ場面はほぼ無くなります。`@riverpod`を付けた関数が`Future`を返せばFutureProvider相当、クラスなら戻り値の型に応じてNotifierかAsyncNotifierになります。StateProviderで書いていた「数値1つを画面から書き換える」用途も、3系では`build`と変更メソッドを持つNotifierで書きます。

## @riverpodによるコード生成の現行書式とbuild\_runner運用

3系のコード生成でいちばん変わったのが、関数プロバイダの引数型です。2.x時代は`CounterRef`のような生成された専用型を受け取っていましたが、riverpod\_generator 2.6.0で非推奨になり、3系では専用型そのものが削除されました。現行の書式は`Ref ref`です。

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

part 'counter.g.dart';

@riverpod
String label(Ref ref) => 'Hello world';

@riverpod
class CounterNotifier extends _$CounterNotifier {
  @override
  int build() => 0;

  void increment() => state++;
}

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

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Scaffold(
      appBar: AppBar(title: Text(ref.watch(labelProvider))),
      body: Center(child: Text('$count')),
      floatingActionButton: FloatingActionButton(
        onPressed: () => ref.read(counterProvider.notifier).increment(),
        child: const Icon(Icons.add),
      ),
    );
  }
}
```

状態とロジックをまとめたいクラスには`@riverpod`を付け、`_$クラス名`を継承して`build`で初期値を返します。初期化処理は`build`に集約し、`ref`は`this.ref`として使えます。表示は`ref.watch(counterProvider)`、変更は`ref.read(counterProvider.notifier)`経由でメソッドを呼ぶ、という分担です。

ここで生成されるProvider名は`counterNotifierProvider`ではなく`counterProvider`です。riverpod\_generator 4.0.9の既定オプション`provider_name_strip_pattern`が`Notifier$`になっており、クラス名末尾のNotifierを取り除いてから`Provider`を付けるためです。手元で生成した`.g.dart`でも、`CounterNotifier`は`counterProvider`、`ProfileNotifier`は`profileProvider`、末尾がNotifierでない`TodoList`は`todoListProvider`になりました。生成名が想定と違うときは、build.yamlでこのパターンを上書きできます。

生成の実行は`dart run build_runner watch`です。既存の解説でよく見る`-d`（`--delete-conflicting-outputs`）は、build\_runner 2.15.0で削除済みオプションの一覧に移りました。2.16.2で渡すと「These options have been removed and were ignored: –delete-conflicting-outputs」という警告が出るだけで、生成自体は続行します。2.16.0からは生成物が食い違っていれば既定で作り直される動作に変わっており、手で編集した生成ファイルを残したい場合だけ`--keep-modified-outputs`を付けます。CIなど1回だけ動かす場面では`build`サブコマンドを使います。

キャッシュの寿命は注釈で指定します。`@riverpod`の`keepAlive`は既定でfalseで、手元でもリスナーを閉じて50ミリ秒待つとカウンターが0に戻りました（破棄されて作り直された）。アプリの生存期間中ずっと保持したい設定値やクライアントは`@Riverpod(keepAlive: true)`と書きます。手書きのProviderでは`Provider(isAutoDispose: true)`と引数で指定します。2.x時代の`Provider.autoDispose`というビルダー経由の書き方も3.4.3に残っているため、既存コードを一斉に書き換える必要はありません。

## 非同期データと引数付きProviderの使い方

### AsyncValueとswitchによる状態別の表示分岐

APIから取得する値は、`Future`を返す関数に`@riverpod`を付けて定義します。読み出し側には`AsyncValue`が届き、最初の状態は`AsyncLoading`です。3系ではDart 3のパターンマッチで分岐する書き方が素直です。

```
@riverpod
Future<User> user(Ref ref, int id) async {
  final client = ref.watch(apiClientProvider);
  return client.fetchUser(id);
}

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

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final user = ref.watch(userProvider(id));
    return switch (user) {
      AsyncData(:final value) => Text(value.name),
      AsyncError(:final error) => Text('読み込みに失敗しました: $error'),
      _ => const CircularProgressIndicator(),
    };
  }
}
```

再取得中の扱いには注意が要ります。値を取得済みのProviderを`ref.invalidate`や`ref.refresh`で取り直すと、状態は`AsyncLoading`に戻らず、`AsyncData`のまま`isLoading`がtrueになりました（riverpod 3.4.3で実測）。上のswitchは再取得中も古い値を表示し続けるということです。引っ張って更新する画面でインジケーターを出したいなら、`user.isRefreshing`を別途見ます。`when`を使う場合も`skipLoadingOnRefresh`の既定がtrueなので、同じく古い値が描画されます。

### 引数付きProvider（family）の書き方とキャッシュ単位

上の`user(Ref ref, int id)`のように、`Ref`の後ろに引数を足すとfamily（引数ごとに別の状態を持つProvider）になります。生成コードでは`UserFamily`というクラスが作られ、呼び出しは`userProvider(1)`の形です。2.xの`FutureProvider.family`を手で書く必要はありません。

キャッシュは引数の値ごとに1つです。`userProvider(1)`を2か所から購読し、`userProvider(2)`を1か所から購読したところ、取得関数の実行は2回でした。`userProvider(1) == userProvider(1)`もtrueです。引数にクラスを渡す場合はこの比較が`==`で行われるため、`==`と`hashCode`を実装していないクラスのインスタンスを毎回新しく作って渡すと、同じ内容でも別のキャッシュが作られます。同じインスタンスを渡す場合は共有されます。

### Providerのselectによる再描画範囲の限定

状態がオブジェクトで、画面がその一部だけを使うなら`select`で購読範囲を絞ります。名前と年齢を持つ状態で、`select((p) => p.name)`と`select((p) => p.age)`を別々に購読し、年齢だけを更新したところ、通知は年齢側の1回だけで名前側は0回でした。

```
final name = ref.watch(profileProvider.select((p) => p.name));
```

選び出した値どうしは`==`で比べられます。`select`で通常のListや等価比較を実装していないクラスのインスタンスを毎回新しく返すと、内容が同じでも「変わった」と判定されるので、返すのは文字列や数値などの比較が効く値にします。

### invalidateとrefreshの使い分け

どちらもProviderを作り直しますが、`ref.refresh`はその場で作り直して直後の値を返し、`ref.invalidate`は現在の状態を破棄します。購読中なら通常は次のイベントループで再計算されますが、その前にreadすればその時点で再計算され、未購読なら再び参照されるまで遅延します。`invalidate`を同じProviderに3回続けて呼んでも、再取得は1回でした。値を使わないなら`invalidate`で足ります。`RefreshIndicator`のように完了を待ちたい場面では、`ref.refresh(userProvider(id).future)`とすれば取得完了まで待つ`Future`が手に入ります。

`invalidate`には2つの使い方があります。1つは`ref.invalidate(userProvider)`のように引数を付けずにfamily全体を渡す書き方で、`userProvider(1)`と`userProvider(2)`の両方が再取得されました。もう1つは`asReload: true`で、このときは状態が`AsyncLoading`に変わります（`hasValue`はtrueのまま）。上のswitchなら古い値ではなくインジケーターが出るので、ログアウト後の再取得のように古い値を見せたくない場面に向きます。

## Riverpod 2.xから3系への移行で壊れる箇所

3系への移行で確認する代表的な変更を次に示します。コンパイルエラーになる変更に加え、更新通知や例外伝播など実行時の挙動が変わるものも含みます。一覧の原文は[公式の3.0移行ガイド](https://riverpod.dev/docs/3.0%5Fmigration)にあります。

| 変更点          | 2.xの書き方                      | 3系での対応                |
| ------------ | ---------------------------- | --------------------- |
| レガシーProvider | 本体importで利用                  | legacy.dart を追加import |
| Refのサブクラス    | FutureProviderRef など         | Ref に統一               |
| AsyncValue   | valueOrNull                  | value（保持値がなければnull）   |
| 更新の通知        | Providerごとに == または identical | \== で判定               |
| エラーの伝播       | 元の例外がそのまま                    | ProviderException で包む |

レガシーProviderのimportには落とし穴があります。`StateNotifierProvider`と`StateProvider`は`riverpod`側と`flutter_riverpod`側のどちらのlegacy.dartにも入っていますが、`ChangeNotifierProvider`はFlutterに依存するため`flutter_riverpod/legacy.dart`にしか存在しません。Flutterアプリでは次の1行で統一するのが安全です。

```
import 'package:flutter_riverpod/legacy.dart';
```

ただしlegacy.dartは移行のための待避先です。新規実装で`StateNotifier`を選ぶ理由はほとんど無く、`Notifier`と`AsyncNotifier`へ寄せます。初期化処理と他のProviderの`ref.watch`を`build`にまとめられるうえ、クラスに`@riverpod`を付けて生成されるのもNotifier系で、StateNotifierProviderは生成できません。後述する永続化（`persist`）も`AnyNotifier`の拡張メソッドなので、`StateNotifier`からは呼べません。一方、自動リトライはレガシーProviderにも効くため、移行しないと使えない機能ではありません。両者の具体的な書き分けは[NotifierProviderとStateNotifierProviderの違い](/tech/details/2819/)で解説しています。

更新判定が`==`に変わった点も見落としやすい変更です。`Notifier<List<String>>`の中で`state.add('a')`のあと`state = state`と再代入しても、リスナーへの通知は0回でした。同じインスタンスなので等価と判定されるためです。`state = [...state, 'b']`と新しいリストを作って代入すると通知は1回届きます。どうしても同一インスタンスを書き換えたい場合は、Notifier側で`updateShouldNotify`を上書きします。

`ProviderException`によるラップは、別のProviderを`ref.watch`して例外が再送出されるときに発生します。自分で`AsyncValue.guard`を通した例外はそのまま`AsyncValue.error`に入るため、catch句で型判定している箇所は経路ごとに確認が必要です。

## 3系で追加された実務向けAPIの実際の挙動

ここからは3系の新機能について、[公式のWhat is new in Riverpod 3.0](https://riverpod.dev/docs/whats%5Fnew)の説明と、pub.devで配布されているパッケージの実装の両方を突き合わせて確認します。説明の言い回しだけでは読み取れない上限値や既定値が実装側に書かれているためです。

### 自動リトライの上限10回と対象外の例外型

3系ではProviderのbuildが失敗すると自動で再実行されます。既定の挙動は`ProviderContainer.defaultRetry`に書かれていて、遅延は200ミリ秒から始まる指数バックオフ、上限は6400ミリ秒、再試行回数は10回で打ち切りです。`Exception`を投げ続けるFutureProviderを購読したところ、3.2秒の間に5回実行されました（初回のあと200・400・800・1600ミリ秒の間隔）。

打ち切り条件はもう1つあり、`error is ProviderException || error is Error`に該当する例外は最初から再試行されません。`StateError`（`Error`のサブクラス）を投げる場合は、1.5秒待っても実行は1回だけでした。`Error`はDartにおけるプログラムの誤り（型エラーやnullチェック失敗）を表すため、バグ由来の失敗を叩き続けない設計です。逆に言えば、通信失敗を`Exception`のサブクラスではなく`Error`で投げているコードは、リトライの対象から外れます。

再試行の方針はスコープ単位でも差し替えられます。次の書き方では再試行は2回で止まり、初回を含めた実行は計3回でした。

```
runApp(
  ProviderScope(
    retry: (retryCount, error) {
      if (retryCount >= 2) return null;
      return const Duration(seconds: 1);
    },
    child: const MyApp(),
  ),
);
```

### Ref.mountedによる非同期処理後の生存確認

非同期処理の待機中に画面が閉じられると、完了後の`state`代入が破棄済みProviderへの操作になります。3系では`BuildContext.mounted`と同じ発想の`Ref.mounted`が追加され、await後に生存を確認できるようになりました。`mounted`以外のrefやnotifierのメソッドは破棄後に呼ぶと`UnmountedRefException`を投げる仕様に変わったため、await直後のチェックを習慣にしておくと安全です。なお3.2.0では、リビルド後の古いrefで`mounted`がtrueを返す不具合が修正されています。実行環境のバージョンが3.2.0未満なら、この挙動は当てにできません。

### 実験的APIの制約：永続化の保持期間とMutationの同時実行

オフライン永続化は`package:flutter_riverpod/experimental/persist.dart`から提供され、公式ドキュメントも「This feature is experimental and not yet stable」と明記しています。有効化はNotifierの拡張メソッドを`build`内で呼ぶ形です。次は抜粋で、実際には`JsonSqFliteStorage`を返す`storageProvider`、`fromJson`と`toJson`を持つTodoモデル、このNotifierを公開するProviderが別途必要になります。

```
import 'dart:convert';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:flutter_riverpod/experimental/persist.dart';
import 'package:riverpod_sqflite/riverpod_sqflite.dart';

class TodosNotifier extends AsyncNotifier<List<Todo>> {
  @override
  Future<List<Todo>> build() async {
    await persist(
      ref.watch(storageProvider.future),
      key: 'todos',
      encode: jsonEncode,
      decode: (json) => (jsonDecode(json) as List)
          .map((e) => Todo.fromJson(e as Map<String, Object?>))
          .toList(),
    ).future;

    return state.value ?? <Todo>[];
  }
}
```

ここで見落とされがちなのが保持期間です。`StorageOptions`の`cacheTime`は既定で2日に設定されており、期限切れのデータはアプリ再起動時または期限後の読み出し時に削除されます。ユーザー設定を長期保存する用途では、既定の2日という保持期間が要件に合わない場合があります。保持期間を延ばすなら`StorageOptions(cacheTime: ...)`を明示します。なお、状態がJSON化できるクラスで構成されているなら、`package:riverpod_annotation/experimental/json_persist.dart`の`@JsonPersist()`をNotifierに付けることで、`key`と`encode`と`decode`の指定を生成側に任せられます。

同じく実験的なMutationにも注意点があります。実装のコメントに「Currently, mutations do not restrict concurrent calls in any capacity.」とあるとおり、二重実行は抑止されません。送信ボタンの連打対策は、Mutationの状態を見てUI側で無効化する形で自前に用意する必要があります。

## つまずきやすいエラーと切り分けの順番

### No ProviderScopeエラーの原因とスコープ配置

Providerを読む位置が`ProviderScope`の外側にあるときの例外です。`runApp`の引数を包み忘れているケースのほか、`ProviderScope`を`MaterialApp`より内側に置いていて、ルートのNavigatorへ積んだダイアログがスコープの外に出た場合、テストで`pumpWidget`に素のウィジェットを渡している場合にも起きます。テストではウィジェットを`ProviderScope`で包みます。ウィジェットを使わずProviderだけをテストする場合は、`ProviderContainer.test()`を使います。

### 「ref.listen can only be used within the build method」の原因とlistenManual

このメッセージは、`WidgetRef.listen`をbuildの外（`initState`やボタンのコールバック）で呼んだときに出ます。flutter\_riverpod 3.4.3の`consumer.dart`では`assert(debugDoingBuild, 'ref.listen can only be used within the build method of a ConsumerWidget')`と書かれており、assertなのでデバッグ実行でだけ止まります。リリースビルドではassertが外れて例外は出ませんが、`ConsumerWidget`はbuildの開始時に`ref.listen`の購読をすべて閉じる実装です。`initState`で始めた購読は最初のbuildで閉じられて通知が届かず、コールバックから呼んだ購読も次のbuildまでしか生きません。エラーにならないまま監視が抜けるので、デバッグで見た時点で直します。

直し方は2通りです。画面の表示中ずっと監視するならbuildの中で`ref.listen`を呼びます。`initState`で一度だけ購読を始めたいなら、`ConsumerState`で`ref.listenManual`を使います。`listenManual`は購読を返し、ウィジェットの破棄時に自動で閉じられるため、`dispose`で閉じる処理は要りません。

```
class _CartPageState extends ConsumerState<CartPage> {
  @override
  void initState() {
    super.initState();
    ref.listenManual(cartProvider, (previous, next) {
      if (next.hasError) {
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(content: Text('カートの更新に失敗しました')),
        );
      }
    });
  }
  // build は省略
}
```

### build\_runnerの生成失敗とpart宣言・依存制約の確認

まず`part 'ファイル名.g.dart';`の行があるかを確認します。この宣言が無いと生成器は対象ファイルを無視します。次に生成されたProvider名です。クラス名に`Notifier`を付けている場合、既定の除去パターンによって名前から消えるため、`counterNotifierProvider`を参照しているとコンパイルが通りません。`pub get`の段階で止まるなら、build\_runnerを2.17.1以降に上げていないかを見ます。解析器のバージョン不一致はSDKと依存パッケージの制約を調整して解消し、その後に`dart run build_runner build`で出力を作り直します。

### 新しいAPIが見つからない場合のSDK・解決バージョン確認

3系で追加されたクラスやメソッドが解決できないときは、`flutter --version`でDartの版を見て、`pubspec.lock`に記録されているflutter\_riverpodの版と突き合わせます。Dartが3.12未満で指定が`^3.0.0`のような幅のある書き方だと、pubは警告なく3.3.2で解決を終えます。対処はFlutter本体を3.44.0以降へ上げることで、pubspecの書き換えだけでは解決しません。

## Riverpod 3.4系への更新と実験的APIの採用を見送る条件

すべてのプロジェクトで3系へ上げるべきとは考えていません。判断が分かれるのは、Flutterの版を固定しているチームです。

端末検証の都合やCI基盤の制約でFlutter 3.41系以前に固定しているなら、3.4系は入りません。選択肢は、3.3.2で止めてFlutterの更新計画に合わせるか、Flutterごと上げる段取りを先に組むかのどちらかです。決めずに幅の広い指定を置いたままにすると、解決される版が開発者の手元のFlutterによって変わります。`pubspec.lock`をリポジトリで共有し、同じ依存条件で検証できる状態にしてください。

永続化とMutationを前提にした設計も、現時点では勧めません。experimental配下のAPIについては、[riverpodのCHANGELOG](https://pub.dev/packages/riverpod/changelog)に「They may be modified in breaking ways without a major version.」と方針が書かれています。メジャー版を上げずに壊す前提のAPIということです。業務要件として永続化が必須なら、Riverpodの外側にリポジトリ層を置き、保存の実装を差し替えられる形にしておく方が安全です。アプリ全体の層構成は[Flutterアーキテクチャのベストプラクティス](/tech/details/7232/)の考え方が参考になります。

次の更新にも備えておきます。2026年10月26日時点で、GitHubのmasterにある[flutter\_riverpodのCHANGELOG](https://github.com/rrousselGit/riverpod/blob/master/packages/flutter%5Friverpod/CHANGELOG.md)の未リリース欄には、Materialのimportを`package:material_ui`へ移し、`material_ui`を依存に加える変更が載っています。公開前なので内容は変わりえますが、次のマイナー版では依存解決の結果が変わる前提で`pubspec.lock`の差分を確認してください。Riverpodを前提にしたFlutterアプリの設計・実装を外部に任せる場合は、[Flutter・React Nativeのクロスプラットフォーム開発](/service/apps/cross%5Fplatform/)で相談を受けています。

## よくある質問

### Riverpod 3.0はいつリリースされましたか？

安定版の3.0.0は2025年9月10日に公開されました。その後は3.1.0（2025年12月26日）、3.2.0（2026年1月17日）、3.3.2（2026年6月10日）、3.4系（2026年7月以降）と更新が続いており、2026年10月時点の最新は3.4.3です。マイナー版でもSDK要件が上がる場合があるため、更新時はCHANGELOGとpubspecの`environment`を合わせて確認してください。

### riverpodとflutter\_riverpodはどちらを入れますか？

Flutterアプリなら`flutter_riverpod`です。`riverpod`はFlutterに依存しないコア部分で、サーバーサイドDartやCLIなどウィジェットを使わない環境向けに分かれています。flutter\_riverpodを入れれば依存として自動的に入るので、pubspecに両方書く必要はありません。flutter\_hooksを併用しているプロジェクトでは、代わりに`hooks_riverpod`を入れます。

### @riverpodとriverpod\_annotationの関係は何ですか？

`@riverpod`という注釈を定義しているのが`riverpod_annotation`パッケージで、その注釈を読んで実際のProviderコードを書き出すのが`riverpod_generator`です。前者はdependencies、後者はbuild\_runnerと一緒にdev\_dependenciesへ入れます。バージョンはannotationが4.0.7、generatorが4.0.9と番号がずれていますが、generator 4.0.9のpubspecが`riverpod_annotation: 4.0.7`をバージョン固定で依存しているため、両方に`^`付きで書いておけば整合します。

### StateProviderやStateNotifierProviderはもう使えませんか？

使えます。3系では通常のimportから外れただけで、削除はされていません。`import 'package:flutter_riverpod/legacy.dart';`を追加すれば従来どおり動きます。ただし公式の方向性は`Notifier`と`AsyncNotifier`への移行で、クラスへの`@riverpod`によるコード生成や永続化（`persist`）は、`StateNotifier`では使えません。既存コードは動かしたまま、新規に書く部分からNotifierへ寄せるのが現実的です。

### autoDisposeは3系でどう書きますか？

コード生成を使う場合、`@riverpod`は既定でautoDispose（keepAliveがfalse）です。保持したいときだけ`@Riverpod(keepAlive: true)`と書きます。手書きの場合は`Provider(isAutoDispose: true)`と引数で指定するのが現行の書き方で、2.x時代の`Provider.autoDispose`というビルダー経由の書き方も3.4.3に残っています。`AutoDisposeNotifier`のような専用インターフェースは`Notifier`へ統合されたため、クラスを使い分ける必要はありません。

## 関連記事

- [Riverpodと他の状態管理の違い｜Provider・Bloc・GetXとの比較と選び方【2026年10月】](/tech/details/7039/)
- [Riverpod NotifierProviderの使い方とStateNotifierProviderとの違い【Riverpod 3.0対応】](/tech/details/2819/)
- [FlutterのMVVM実装をRiverpodで書く手順｜公式アーキテクチャガイド準拠のViewModel設計](/tech/details/4443/)
- [Flutterアーキテクチャのベストプラクティス｜公式ガイドのレイヤー設計とディレクトリ構成【Flutter 3.47対応】](/tech/details/7232/)
- [Flutter 3.47とは？material\_ui移行・iOS 15と3.47.7までの修正【2026年10月時点】](/tech/details/16894/)

---

出典: [Riverpodとは？Flutterの状態管理をRiverpod 3系で始める導入・使い方・移行ガイド](<https://www.issoh.co.jp/tech/details/9959/>)（株式会社一創）
