MacOS・Windows対応の開発環境構築（Error対応・Q&A）後半
11. よく起こりうるエラー集
Flutter の環境構築は、正しい順番で進めても途中で止まることがあります。ただし、多くのエラーは無秩序に見えても、実際には
- SDK
- PATH
- Android toolchain
- Xcode
- 実行先
- IDE 拡張 のどこかに分類できます。Flutter 公式も、インストール時のトラブルシューティングページを用意し、各セットアップページで flutter doctor -v を使って不足を切り分ける流れを前提にしています。
この章では、よくあるエラーを
- 症状
- 原因
- 確認
- 解決 の順で整理します。目的は、「エラー文を暗記すること」ではなく、どの層の問題かを見抜けるようになることです。
11-1. flutter: command not found / flutter is not recognized
症状
ターミナルや PowerShell で flutter --version を実行しても、コマンドが見つからないと表示されます。
原因
最も多いのは、Flutter SDK の bin フォルダが PATH に入っていないことです。
次に多いのは、そもそも SDK の展開先が想定と違うことです。Flutter 公式の PATH 設定ページでも、SDK の bin フォルダを PATH に加えることが前提になっています。
確認
mac
flutter --version
PowerShell
flutter --version
解決
- SDK の場所を確認する
- flutter/bin を PATH に追加する
- ターミナルや PowerShell を再起動する
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| PATH未設定 | flutter コマンドが使えない | bin を PATH に追加する |
| SDK場所を誤認 | 違うパスを通してしまう | 実際の展開場所を確認する |
11-2. Flutter SDK not found
症状
VS Code や Android Studio で Flutter SDK が見つからないと表示されます。
原因
IDE 側が SDK の場所を把握できていないか、SDK 自体がまだ入っていない可能性があります。VS Code 経由の導入ページでも、SDK ダウンロードや SDK パス認識がセットアップの中心になっています。
確認
- SDK が本当に存在するかをファイルシステムで確認する
- flutter --version が CLI では通るか確認する
- IDE 側で Flutter コマンドが認識されるかを見る
解決
- SDK を正しい場所に展開する
- IDE の Flutter SDK path を再設定する
- 必要なら VS Code 経由導入ではなく手動導入に切り替える
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| IDEがSDK位置を知らない | 補完や実行が効かない | SDK path を再設定する |
| SDK未導入 | 何も進まない | SDK を先に導入する |
11-3. Android licenses not accepted
症状
flutter doctor -v で Android licenses に関する警告が出ます。
原因
Android SDK のライセンス同意が完了していないためです。Flutter 公式の Android 開発セットアップでも、flutter doctor --android-licenses を実行して同意を進める手順が明示されています。
確認
flutter doctor -v
flutter doctor --android-licenses
PowerShell:
flutter doctor -v
flutter doctor --android-licenses
解決
flutter doctor --android-licenses を実行し、表示される確認に同意します。
完了後、再度 flutter doctor -v を実行して警告が消えるかを確認します。
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| ライセンス未同意 | Android toolchain が未完了扱いになる | flutter doctor --android-licenses を実行する |
| 再確認しない | 直ったか不明のままになる | flutter doctor -v を再実行する |
11-4. Android toolchain not configured
症状
Android 関連の doctor 項目が未解決のままで、Android 向けに run できません。
原因
Android Studio が未導入、Android SDK が不足、または Android 関連設定が途中の可能性があります。
Flutter 公式の Android setup は、Android Studio、SDK Manager、Device Manager を使った構成を前提にしています。
確認
flutter doctor -v
flutter devices
解決
- Android Studio を入れる
- SDK Manager で Android SDK を確認する
- 必要な system image を入れる
- flutter doctor --android-licenses を実行する
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| Android SDK未導入 | Android 実行できない | Android Studio + SDK を入れる |
| 設定途中 | doctor で未完了表示が残る | 手順を上から潰す |
11-5. No devices available
症状
flutter devices に何も表示されず、flutter run も実行先を見つけられません。
原因
Emulator / Simulator / 実機が起動していないことがほとんどです。Flutter 公式の Quick start でも、実行先の確認を前提に run を進めています。
確認
flutter devices
flutter emulators
PowerShell:
flutter devices
flutter emulators
解決
- Android Emulator を起動する
- Mac なら iOS Simulator を起動する
- 必要なら実機を接続する
- 再度 flutter devices を確認する
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| 実行先未起動 | run できない | 先に実行先を起動する |
| devices確認不足 | 原因が見えない | flutter devices を毎回見る |
11-6. Xcode not installed / not configured
症状
Mac で iOS 関連の doctor 項目が未設定になり、iOS run ができません。
原因
Xcode 本体が未インストール、または command-line tools や初回セットアップが完了していない可能性があります。Flutter 公式の iOS setup は、Xcode とその周辺設定を前提にしています。
確認
flutter doctor -v
xcode-select -p
解決
- App Store から Xcode を入れる
- Xcode を一度起動する
- xcode-select と xcodebuild -runFirstLaunch を実行する
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| Xcode未導入 | iOS 開発不可 | Xcode を入れる |
| 初回設定不足 | doctor が未完了になる | command-line tools を設定する |
11-7. Xcode license not accepted
症状
doctor や build 実行時に Xcode license 未同意に関する警告が出ます。
原因
Xcode のライセンスにまだ同意していません。Flutter 公式の iOS setup でも、sudo xcodebuild -license を実行するよう案内しています。
確認
flutter doctor -v
解決
sudo xcodebuild -license
その後、再度 flutter doctor -v を実行します。
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| ライセンス未同意 | iOS toolchain が止まる | sudo xcodebuild -license を実行する |
| 再確認不足 | 状態が不明のまま | doctor を再実行する |
11-8. Windows desktop toolchain unresolved
症状
Windows で desktop 関連の doctor 項目が unresolved になっています。
原因
Windows desktop 向けの必要ツールが不足しています。Flutter 公式の Windows setup でも、flutter doctor -v に従って不足 toolchain を解消する流れが示されています。
確認
flutter doctor -v
flutter devices
解決
Windows setup ページの要件を確認し、不足ツールを追加したうえで、再度 flutter doctor -v を実行します。
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| 必要ツール不足 | desktop 開発できない | Windows setup に従って不足を埋める |
| doctor未確認 | 何が足りないかわからない | flutter doctor -v を基準にする |
11-9. VS Code拡張が認識されない
症状
Flutter コマンドが出ない、補完が効かない、Hot Reload ボタンが見つからない。
原因
Flutter / Dart extension が未導入、または有効化されていない可能性があります。Flutter 公式の VS Code サポートページも、Flutter extension を前提にしています。
確認
- Extensions で Flutter が有効か確認
- Command Palette で Flutter: コマンドが出るか確認
解決
- Flutter extension を再インストール
- VS Code を再起動
- 必要ならワークスペースを開き直す
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| 拡張未導入 | 開発体験が不完全になる | Flutter / Dart 拡張を入れる |
| 拡張無効 | コマンドが出ない | 有効化して再起動する |
11-10. エミュレータ / シミュレータが起動しない
症状
Android Emulator や iOS Simulator が起動しない、または起動しても Flutter から見えない。
原因
Android なら仮想デバイス未作成、system image 未取得、マシン負荷や仮想化設定の問題が多いです。
iOS なら Xcode 初回設定不足や Simulator 起動前の状態が原因になりやすいです。Flutter 公式の Android / iOS setup は、いずれも GUI 側設定完了を前提にしています。
確認
flutter emulators
flutter devices
PowerShell:
flutter emulators
flutter devices
解決
- Android Studio の Device Manager で仮想端末を再確認する
- system image を入れ直す
- Xcode / Simulator を一度明示的に起動する
- 再度 flutter devices を実行する
課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| 仮想端末未作成 | 起動対象がない | Device Manager / Simulator を設定する |
| 起動はしたが認識されない | Flutter run できない | flutter devices で見えるか確認する |
12. Mac用クイックルート
ここでは、Mac で最短で環境構築をやり直したいときの導線をまとめます。
Flutter 公式の VS Code install、Android setup、iOS setup を踏まえると、
Android を先に通し、その後 iOS を追加する
流れがもっとも安定します。
12-1. 最短手順
- VS Code を入れる
- Flutter extension を入れる
- Flutter SDK を入れる
- PATH を通す
- Android Studio を入れる
- Android Emulator を作る
- 必要なら Xcode を入れる
- flutter doctor -v を実行
- flutter create → flutter run
12-2. コピペ用コマンド一覧
xcode-select --install
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
flutter --version
dart --version
flutter doctor -v
flutter doctor --android-licenses
flutter emulators
flutter devices
flutter create my_first_flutter_app
cd my_first_flutter_app
flutter run
※ xcode-select --install は command-line tools 未導入時のみ有効です。Xcode 本体が必要な場合は App Store から別途導入します。Flutter 公式の iOS setup / VS Code install でも、この初期設定が案内されています。
12-3. GUI操作一覧
- VS Code をインストール
- Flutter extension をインストール
- Android Studio をインストール
- SDK Manager を確認
- Device Manager で Android Emulator を作る
- 必要なら Xcode をインストール
12-4. 完了チェックリスト
- flutter --version が通る
- flutter doctor -v に致命的エラーがない
- Android Emulator が flutter devices に見える
- 必要なら iOS Simulator も見える
- flutter run で起動する
12-5. この節の課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| 手順が前後する | どこで壊れたか不明になる | Android を先に通す |
| iOSを最初から混ぜる | 切り分けが難しくなる | Android → iOS の順で進める |
| doctorを飛ばす | 不足を見逃す | 必ず途中で flutter doctor -v を挟む |
13. Windows用クイックルート
Windows で最短で環境構築をやり直したいときは、
- Flutter SDK
- VS Code
- Android Studio
- Android Emulator の流れが基本です。Flutter 公式の VS Code install では、Windows では Git for Windows の導入も案内されています。
13-1. 最短手順
- Git for Windows を入れる
- VS Code を入れる
- Flutter extension を入れる
- Flutter SDK を入れる
- PATH を通す
- Android Studio を入れる
- Android Emulator を作る
- flutter doctor -v を実行
- flutter create → flutter run
13-2. コピペ用コマンド一覧
$env:Path = "C:\dev\flutter\bin;" + $env:Path
flutter --version
dart --version
flutter doctor -v
flutter doctor --android-licenses
flutter emulators
flutter devices
flutter create my_first_flutter_app
Set-Location my_first_flutter_app
flutter run
このコマンド列は、Flutter 本体、Android licenses、実行先確認、新規作成、実行確認までを含んでいます。Flutter 公式の Windows / Android / VS Code 導線に沿う形です。
13-3. GUI操作一覧
- Git for Windows をインストール
- VS Code をインストール
- Flutter extension をインストール
- Android Studio をインストール
- SDK Manager を確認
- Device Manager で Android Emulator を作る
13-4. 完了チェックリスト
- flutter --version が通る
- flutter doctor -v に致命的エラーがない
- Android Emulator が flutter devices に見える
- flutter run で起動する
13-5. この節の課題と解決
| 課題 | 何が起きるか | 解決 |
|---|---|---|
| Git未導入 | 一部開発前提が崩れる | Git for Windows を先に入れる |
| Android環境未整備 | 実行先がない | Android Studio と Emulator を整える |
| desktop まで一度にやろうとする | 切り分けが難しい | まず Android で成功させる |
14. 考えてみよう
ここでは、環境構築を単なる作業で終わらせず、なぜその順番で進めるのかを考えます。Flutter を学ぶとき、理解と作業はセットです。
理由を考えながら進めることで、次に別マシンや別プロジェクトで環境構築するときも再現しやすくなります。
14-1. なぜFlutter環境構築はFlutter単体では完結しないのか
Flutter はクロスプラットフォームの開発基盤ですが、最終的にアプリを動かす先は Android、iOS、Windows、macOS などの各OSです。
つまり、Flutter は「共通の土台」であり、そこに各プラットフォームの toolchain が接続されて初めて実行できます。
Flutter 公式が install と platform setup を別々に持っているのは、この構造を反映しています。
考える問い
- Flutter SDK だけで Android / iOS / Windows の実行まで完結しないのはなぜでしょうか。
- 「共通コード」と「開発環境の共通化」は、どこが違うでしょうか。
14-2. なぜ最初に1つの実行先に絞るべきなのか
一度に Android、iOS、desktop を全部やろうとすると、どこで失敗したのかが見えにくくなります。
一方、最初に Android Emulator 1台で成功させれば、Flutter SDK・PATH・エディタ・Android toolchain・run の流れが成立していると確認できます。
その後で iOS や desktop を足すほうが、構造的に切り分けやすいです。
考える問い
- 最初から複数ターゲットを同時に狙うと、どのような混乱が起こるでしょうか。
- Android を最初の成功体験にする利点は何でしょうか。
14-3. なぜ flutter doctor -v を読める必要があるのか
doctor は、環境構築における「健康診断」です。
感覚で調べるより、現在不足しているものを一覧で確認できます。Flutter 公式も install や各 setup ページで doctor を前提にしています。
つまり doctor が読めると、トラブル対応を勘ではなく構造で進められます。
考える問い
- flutter doctor -v を見ずに作業すると、どんな無駄が増えるでしょうか。
- エラー文と doctor の出力は、どう使い分けるべきでしょうか。
14-4. なぜMacとWindowsで学習戦略を変えるべきなのか
iOS が Mac 前提だからです。Windows では Android / Windows desktop が中心になり、Mac では Android の後に iOS を追加できます。
この差を無視すると、「Flutter なら全部同じようにできるはず」という誤解につながります。Flutter の価値はコード共有にありますが、各OSの開発条件までは統一されません。
考える問い
- Mac と Windows で同じ教材を使っていても、なぜ進め方を変える必要があるのでしょうか。
- 自分の目的が Android 中心なのか、iOS まで含むのかで、何を優先すべきでしょうか。
15. まとめ
この章全体を通して、環境構築は Flutter SDK を入れるだけの作業ではないことが見えてきたはずです。
本質は、
- Flutter SDK
- エディタ
- 各プラットフォームの toolchain
- 実行先
- 診断コマンド をつなげて、実際に開発可能な状態を作ることです。
Flutter 公式の install / quick / platform setup が複数ページに分かれているのも、その構造を反映しています。
15-1. 要点の箇条書きまとめ
- Flutter 環境構築は、Flutter SDK、エディタ、プラットフォームごとの toolchain、実行先の4要素で考えると整理しやすい。 (docs.flutter.dev)
- Mac と Windows は、Flutter SDK・VS Code・Android 開発環境の多くを共通化できるが、iOS 開発は Mac 前提である。 (docs.flutter.dev)
- 新規ユーザーは stable channel を使うのが基本であり、Flutter SDK archive でも stable は new users 向けとされている。 (docs.flutter.dev)
- 最初は Android 環境を先に整え、flutter doctor -v、flutter devices、flutter create、flutter run を通すのが最も失敗しにくい。 (docs.flutter.dev)
- Mac では、その後に Xcode、command-line tools、iOS Simulator を追加することで iOS 学習へ進める。 (docs.flutter.dev)
- flutter doctor -v は、環境構築の正否を判断する中心的な診断コマンドである。 (docs.flutter.dev)
- インストール完了の本当の基準は、新規アプリを作成し、起動し、Hot Reload が効くことである。 (docs.flutter.dev)
15-2. この章で身につけた視点
この章で本当に身につけたいのは、「手順を覚えること」だけではありません。
いま起きている問題が、SDK の問題なのか、toolchain の問題なのか、実行先の問題なのかを切り分ける視点です。
この視点があると、別のPCで環境構築するときも、Flutter バージョンを更新したあとも、落ち着いて原因を追えるようになります。
16. 参考文献
- Flutter documentation
- Install Flutter
- Install Flutter using VS Code
- Install Flutter manually
- Flutter SDK archive
- Add Flutter to your PATH
- Troubleshooting installation
- Set up and test drive Flutter
- Create a new Flutter app
- Visual Studio Code
- Android Studio and IntelliJ
- Set up Android development
- Set up iOS development
- Set up macOS development
- Set up Windows development
- Desktop support for Flutter
- FAQ
- Dart: What’s new