FVMとは？Flutter SDKをプロジェクト単位で固定する運用とCI設定【2026年8月時点】

FVMはFlutter SDKの版をプロジェクトごとに固定し、開発者間とCIの環境差を消すためのCLIツールです。2026年8月時点の安定版は3.47.0（Dart 3.13.0、2026年8月12日公開）で、直近12か月に出た安定版は38本、単純平均で9.6日に1本という頻度でした。この記事では版解決の仕組み、.fvmrcの設定キー、Gitへ含める範囲、CI構成、そして導入を見送ってよい条件までを一次情報から整理します。

まとめ：版のずれが実害になるプロジェクトから順に入れる

結論から言えば、FVMは「複数人またはCIが同じリポジトリをビルドする」プロジェクトで先に入れる価値があります。プロジェクトが1つしかないなら、SDKを1本だけ置いてPATHを通す構成のほうが管理対象は少なく済みます。分かれ目は人数ではなく、版が食い違ったときに壊れるもの（CIの成果物、リリースビルド）の有無です。

導入の実作業はfvm use 3.47.0を1回叩くだけで、リポジトリには.fvmrcが1ファイル増えます。参加者はfvm installで同じ版を引き、以降はfvm flutter経由で実行する形です。詰まるのはコマンドではなくGitへ含める範囲とIDEのSDKパス設定なので、この2点を先に決めてから配ってください。キャッシュは1版あたり約1.8〜2.1GBを消費します。

FVMがFlutter SDKの版を切り替える仕組みと解決の順序

FVMはFlutter本体を書き換えるツールではありません。SDKを複数キャッシュしておき、どの版を指すかをシンボリックリンクで切り替えるだけの薄い層です。この設計が、後述するGit除外やIDE設定の理由をそのまま決めています。

Flutter公式のチャンネル切り替えとFVMが担う役割の違い

Flutter本体にもflutter channelとflutter upgradeという切り替え手段があります。ただしこれはマシンに入った1本のSDKを書き換える操作で、切り替えた瞬間に同じマシン上の全プロジェクトへ影響が及びます。FVM公式のFAQも、チャンネルの更新自体はFlutter標準の挙動を上書きせずflutter upgradeを使うと明示しました。FVMが担うのは「プロジェクトごとに別の版を向ける」という一点であり、SDKの入手や更新そのものを置き換えるものではありません。

裏を返せば、プロジェクトが1つしかないマシンではこの一点の価値がほぼ生まれません。SDK本体の導入手順はFlutterの環境構築｜Windows・macOS別のSDK導入とflutter doctor診断で扱っています。

グローバルキャッシュとプロジェクト内リンクで分ける二層構造の中身

FVMは実体のSDKをマシン共通のキャッシュへ置き、プロジェクト側には参照だけを置きます。プロジェクト直下に作られる.fvmディレクトリの中身は、公式ドキュメントによると次の4つです。

• flutter_sdk：キャッシュ内のSDKを指すシンボリックリンク
• fvm_config.json：旧形式の設定ファイル（非推奨）
• release：FVMが記録する内部ファイル
• version：設定を作成したFVMの版を記録する内部ファイル

実体はキャッシュ側にあるため、同じ3.47.0を10プロジェクトで固定してもディスク上のSDKは1本です。キャッシュ先はFVM_CACHE_PATHで変更でき、旧来のFVM_HOMEは非推奨として残っています。

版の解決が.fvmrcからsystem PATHまで4段階で決まる順序

どの版が使われるかは、公式FAQが示す次の順序で決まります。第1にプロジェクト直下の.fvmrc、第2に親ディレクトリをさかのぼった.fvmrc、第3にfvm globalで設定したグローバル版、第4にsystem PATH上のFlutterです。

親ディレクトリまで探索する仕様は、リポジトリ直下に1本.fvmrcを置けば配下すべてに効くという設計でもあります。逆にモノレポでは、階層のどこに置いたかで一部パッケージだけ別の版になる事故が起きます。迷ったらfvm doctorで解決元を確認してください。

安定版が9.6日に1本という公開頻度の実測と版を固定しない場合の実害

リリース頻度とずれたときの結果を数字で押さえます。以下はFlutter公式の配布メタデータ（releases_macos.json）を2026年8月18日に取得して集計した値です。

直近12か月で安定版が38本という公式配布データからの集計結果

2025年8月18日から2026年8月18日までに公開された安定版は38本でした。単純平均すると9.6日に1本です。内訳は3.35系・3.38系・3.41系・3.44系の4系列にまたがり、3.38系だけでも3.38.0から3.38.10まで11本が出ています。

この頻度は「半年に一度メジャーを追えばよい」という運用感覚とかみ合いません。固定しなければ、flutter upgradeを叩いた時期次第で手元の版が散らばります。

3.44.9の6日後に3.47.0が出た事例に見る版ずれの起き方

直近の並びが分かりやすい例です。3.44.9が2026年8月6日に出て、その6日後の8月12日に3.47.0（Dart 3.13.0）が公開されました。パッチ更新のつもりでflutter upgradeを叩いた人と叩かなかった人の間で、系列そのものが変わります。Dart SDKも3.12.2から3.13.0へ動き、lintの挙動まで揃わなくなります。

系列をまたぐ更新で何が変わるかは版ごとに違い、たとえばFlutter 3.44とは？SPM既定化とHCPPで変わる移行判断で扱ったSPMの既定化のように、ビルド設定へ踏み込む変更も含まれます。固定していないリポジトリでは、こうした変更が「誰かのマシンでだけ再現するビルドエラー」として現れます。

キャッシュ1版あたり約1.8〜2.1GBというディスク消費の見積もり

3.47.0の公式配布アーカイブへHTTPヘッダを投げて実測したところ、Windows版のzipが1,927,280,652バイト（約1.79GB）、macOS arm64版のzipが2,257,377,039バイト（約2.10GB）でした。展開後はこれより増え、flutter precacheの成果物が加わればさらに膨らみます。

目安として、常用する2〜3版を残し、それ以外はfvm removeで落としてください。FVM 4.1.0（2026年5月5日公開）ではgitキャッシュの再構成によるインストール高速化とディスク削減が入り、旧版から上げると初回だけ再構成が走ります。

導入手段の選び方とfvm installからfvm useまでの初期設定

導入経路は複数あり、つまずくのは対応プラットフォームの範囲です。

インストール手段4系統の使い分けと対応プラットフォームの範囲

公式が案内する導入手段は次の4系統です。実務ではmacOSとLinuxがスクリプトかHomebrew、WindowsがChocolateyか配布アーカイブ、CIはDartのグローバルパッケージ、という振り分けが素直です。

対応範囲はmacOSがx64とarm64、Linuxがx64・arm64・riscv64、WindowsはChocolatey経由がx64で、配布アーカイブならarm64も選べます。

fvm useで版を固定するまでの実作業と生成されるファイル

プロジェクトへ版を固定する手順は短く、次の3工程で終わります。

1. 対象リポジトリのルートへ移動する
2. fvm use 3.47.0を実行する（未キャッシュなら自動で取得）
3. 生成された.fvmrcをコミットし、.fvmの除外を確認する

この1回で.fvmrcと.fvmが作られ、既定では.gitignoreとVS Codeの設定まで書き換わります。未知の版を指すときは--force、SDKのセットアップ処理を省くときは--skip-setupを付けてください。チャンネル指定から入る場合は--pinでstableのような可変の指定を固定値へ変換できます。可変のチャンネル名を.fvmrcへ残すと固定の意味が薄れるため、原則は具体版を書きます。

fvm flutterとfvm spawnで実行するコマンドの使い分け

固定後はfvm flutter build apkのように、Flutterコマンドの前にfvmを挟みます。fvm dartも同じ形で、任意のコマンドをプロジェクトのSDK環境で走らせたいときはfvm execを使ってください。固定版とは別の版で一時的に検証する場合はfvm spawn 3.44.9 testのように版を明示します。

入力を減らすなら、公式が案内するalias f="fvm flutter"のようなシェル別名を配布ドキュメントへ書いておきます。直接パスを叩く場合の参照先は.fvm/flutter_sdk/bin/flutterです。

.fvmrcに書く設定項目とチーム全員が同じSDK版を引くための構成

共有されるのは.fvmrcただ1つで、ここに何を書くかがチーム運用の実体です。

.fvmrcの主要キーと既定値および自動で書き換わるファイルの範囲

既定値がtrueのキーが多く、fvm useの時点で周辺ファイルまで自動更新されます。意図しない書き換えを避けたいなら、該当キーをfalseで明示してください。

同じ設定は環境変数でも効き、FVM_CACHE_PATH、FVM_USE_GIT_CACHE、FVM_GIT_CACHE_PATH、FVM_FLUTTER_URLが用意されています。CIランナーだけ挙動を変えるなら、環境変数側で上書きすれば差分がリポジトリに残りません。

flavorsで検証環境と本番環境に別の版を割り当てる書き方

1つのリポジトリで複数の版を並行させたい場面にはflavorsがあります。fvm use 3.44.9 --flavor productionで登録し、実行時はfvm flavor production build apkと呼びます。「本番は3.44系のまま、開発だけ3.47系で検証する」という移行期の運用を設定として明示できる形です。

モノレポではmelos.yamlのsdkPathもFVMが書き換えます。updateMelosSettingsをfalseにすれば止まりますが、その場合は.fvm/flutter_sdkを指す設定を手動で維持してください。flavorを増やせばキャッシュも1版あたり約2GB増えます。

Gitに含めるファイルの切り分けとIDE側のSDKパス設定の実務

導入後の事故はコマンドではなくリポジトリ運用で起きます。

.fvmrcは共有し.fvmディレクトリは除外する切り分けの根拠

コミットするのは.fvmrcだけ、除外するのは.fvmディレクトリ全体、というのが公式の指針です。updateGitIgnoreがtrueならfvm useの時点で除外設定が自動追記されます。理由は前述の二層構造にあり、.fvmの中身は各マシンのキャッシュを指すリンクと内部ファイルでしかないためです。

SDKの実体をリポジトリへ入れる構成は、1版あたり約2GBが履歴に載るため取り返しがつきません。誤って追跡した場合は、除外設定の追記だけでは消えずインデックスから外す操作が要ります。なお.fvm/fvm_config.jsonは旧形式で非推奨のため、これを前提にした古い手順は踏襲しないでください。

VS CodeのSDKパス設定と公式ドキュメントに残る表記の揺れへの対処

updateVscodeSettingsがtrueなら、.vscode/settings.jsonのdart.flutterSdkPathがFVM側から書き込まれます。ここで一点、公式ドキュメントの記載が一貫していません。VS Code向けページでは.fvm/versions/stable、モノレポ向けページとコマンド解説では.fvm/flutter_sdkが示されています（2026年8月18日時点）。

対処は単純です。自分の環境でfvm useを実行したあとに生成された値をそのまま正とし、社内手順書へはその文字列を転記してください。手で書き換える場合も、リンク先の存在をfvm doctorで確認してからにします。Android Studioは設定画面のFlutter SDK pathへ同じリンク先を指定します。

CI環境でSDK版を固定する構成とビルド時間を削るための設定

版固定の効果が最も出るのはCIです。ローカルとCIで版が違えば、固定の意味は半減します。

CIでの実行順序とfvm installを前段へ置く構成の理由

公式が案内する最小構成は次の順序です。SDKの取得をビルド手順から切り離すことで、キャッシュの有無がログ上で切り分けられます。

1. dart pub global activate fvmでFVMを入れる
2. fvm installで.fvmrcの版を取得する
3. fvm flutter build apk --releaseのようにビルドする

版番号をCI設定ファイルへ直書きしないことが要点です。直書きは更新箇所が2つになり、片方だけ上げた状態が事故として現れます。fvm installは引数なしで固定版を読むため、更新は.fvmrcの1箇所で完結します。

更新チェックの停止とキャッシュ共有でCIの所要時間を削るための設定

FVM 4.1.0では、CIやオフライン実行のために更新チェックを止めるオプションが入りました。同版のgitキャッシュ改善（一度だけ再構成が走る）と合わせ、取得時間とディスク消費が下がっています。ランナー間で共有したい場合はFVM_CACHE_PATHで共有ストレージを指し、再ダウンロードそのものを避けます。

1版あたり約2GBの転送を毎回走らせれば、ビルド時間の大半がSDK取得で消えます。

GitHub Actions専用アクションとの使い分けを決める判断基準

CIだけを見るなら、FVMではなくsubosito/flutter-action（v2.23.0・2026年3月25日公開）のような専用アクションでも版指定とキャッシュは成立します。判断の基準は「ローカルとCIで版の定義を1箇所にまとめたいか」の一点です。専用アクションはワークフローのYAMLへ版を書くため、定義がリポジトリ内で二重化します。

手元の版ずれが実害になっているなら、FVMへ寄せて.fvmrcを単一の情報源にする構成が保守しやすくなります。開発者が1人でCIの再現性だけが目的なら、専用アクション単体で足ります。

FVMを採用する条件と別の版管理手段だけで足りる場面の切り分け方

FVMは「入れておけば安心」の類ではなく、管理対象を1つ増やす選択です。

版管理手段5系統の比較と選定時に確認すべき保守状況の対応関係

候補に挙がる手段を、固定できる単位と保守の状況で並べます。更新が止まったものは新しいFlutter系列に追随できません。

FVMは4.1.2が2026年6月25日、4.0.0が2025年10月30日の公開です。3.2.1（2024年8月26日）から4.0.0まで約14か月空いており、この期間の解説記事は3系の前提のままである可能性が高いという読み方もできます。参照する手順記事の日付は必ず確認してください。

導入を見送ってよい2条件とそれでも入れるべきになる分岐点の見極め

見送ってよいのは次の2条件が揃うときです。第1に、Flutterのプロジェクトがそのマシンに1つしかないこと。第2に、CIが無いか、あってもビルド成果物を配布していないこと。この状態でFVMを入れても、増えるのは管理対象と学習コストだけで、防げる事故が存在しません。

分岐点は明確です。2人目の開発者が参加した時点、またはCIでリリースビルドを作り始めた時点で入れてください。どちらかが起きた後は、版のずれが「手元では通るのにCIで落ちる」形で現れ、原因究明に時間を取られます。Flutterを継続採用するかどうかの判断材料はFlutterの将来性を数値で判断する｜リリース実績・国内案件数・競合の現在地で扱っています。

受託開発で引き継ぎ資料へ落とすべき版まわりの記載項目とその粒度

外注や引き継ぎが絡む場合、.fvmrcがあるだけでは足りません。資料へ落とすのは、固定中のSDK版とDart版、flavorの対応表、変更したキャッシュ先の環境変数、そして版を上げる判断を誰が行うかの4点です。ここが空欄のまま引き渡されたリポジトリは、最初の系列更新で止まります。SDKではなくパッケージ側の版を固定する論点はFreezed（Flutter）とは？データクラスとUnion型の生成と依存の固定で扱っています。

版の固定と更新の運用まで含めて設計を任せたい場合は、Flutter / React Nativeによるクロスプラットフォーム開発で、開発環境の定義から引き継ぎ資料の整備まで相談を受け付けています。既存リポジトリの版が散らばっている状態からの整理も対象です。

よくある質問

FVMの導入判断と運用でよく問われる点を、公式ドキュメントの記載と実測値をもとに答えます。

FVMを入れるとFlutter本体の入れ直しが必要になりますか？

不要です。FVMはキャッシュへ別途SDKを取得してプロジェクトからそこを指すだけなので、system PATH上の既存Flutterはそのまま残せます。解決順序でもsystem PATHは最後の候補です。ただし両方が残るとfvmを付け忘れたコマンドが既存SDKで走るため、シェル別名で付け忘れを防いでください。

.fvmディレクトリはGitにコミットすべきですか？

コミットしません。公式は.fvmrcのみを共有し、.fvmディレクトリ全体を除外する構成を示しています。updateGitIgnoreが既定のtrueなら、fvm useの実行時に除外設定が自動追記されます。.fvmの中身はキャッシュを指すリンクと内部ファイルで、他マシンで再現しても意味がありません。

FVMとpuroやmiseはどちらを選べばよいですか？

Flutterだけを固定したいならFVM、Node.jsなど複数言語をまとめて固定したいならmiseやasdfが噛み合います。puroもプロジェクト単位の固定に対応しますが、直近リリースは1.5.0（2025年11月28日）で、FVMの4.1.2（2026年6月25日）より更新間隔が空きました。新しい系列への追随を重く見るなら、履歴が動いている側が無難です。

CIで毎回SDKをダウンロードする時間を減らせますか？

減らせます。FVM_CACHE_PATHでランナー間の共有ストレージをキャッシュ先に指定すれば、SDKの再取得そのものを回避できます。FVM 4.1.0以降は更新チェックを止めるオプションとgitキャッシュの再構成も入りました。配布アーカイブの実測は3.47.0のmacOS arm64版で約2.10GBあり、取得を避ける効果は小さくありません。

fvm useで指定する版はstableのようなチャンネル名でもよいですか？

指定は通りますが、固定の目的からは外れます。チャンネル名は時間とともに指す実体が変わるため、参加者ごとに引く版がずれます。直近12か月で安定版は38本、平均9.6日で内容が動く計算です。チャンネル指定から入るときは--pinで具体版へ落とし、.fvmrcに固定値が残る状態にしてください。

関連記事

• Flutterの環境構築｜Windows・macOS別のSDK導入とflutter doctor診断：FVMを入れる前段のSDK本体の導入と診断
• Flutter 3.44とは？SPM既定化とHCPPで変わる移行判断：系列をまたぐ更新で変わる内容の実例
• Flutterの将来性を数値で判断する｜リリース実績・国内案件数・競合の現在地：継続採用そのものの判断材料
• Flutter Webとは？CanvasKitとWasmの描画差・SEO制約・採用条件：Web出力を対象に含める場合
• FlutterとReact Nativeの違いと選び方｜2026年の判断基準：選定まで戻って比較する場合