Flutter開発で環境構築にハマるポイントまとめ

Flutter
この記事は約18分で読めます。

この記事の最終更新日: 2026年6月16日

Flutterは、1つのコードベースでiOS・Android・Web・デスクトップなどに対応できる便利なフレームワークです。

しかし、実際にFlutter開発を始めようとすると、最初の環境構築でつまずく人は少なくありません。

特に、次のような状態になりがちです。

Flutter SDKは入れたのに、flutter doctorでエラーが出る
Android Studioを入れたのに、Android実機で起動できない
Xcodeを入れたのに、iOSシミュレーターで動かない
CocoaPodsのエラーでiOSビルドが通らない
VS CodeでFlutterプロジェクトを開いたのに補完が効かない

Flutter自体は便利ですが、実際には Flutter SDK・Dart・Android Studio・Android SDK・Xcode・CocoaPods・VS Code/Android Studioの拡張機能 など、複数のツールが連携して動きます。

この記事では、Flutter開発の環境構築でハマりやすいポイントを、初心者向けにまとめます。

  1. Flutter環境構築は、なぜハマりやすいのか
  2. まず確認すべきは flutter doctor
  3. ハマりポイント1：Flutter SDKのパスが通っていない
    1. よくある失敗
  4. ハマりポイント2：Android Studioを入れたのにAndroid SDKが足りない
    1. よくある失敗
  5. ハマりポイント3：Androidライセンスに同意していない
    1. よくある失敗
  6. ハマりポイント4：Android Emulatorが起動しない
    1. よくある失敗
  7. ハマりポイント5：Xcodeを入れたのにiOSビルドできない
    1. よくある失敗
  8. ハマりポイント6：CocoaPodsが入っていない
    1. よくある失敗
  9. ハマりポイント7：VS CodeにFlutter拡張を入れていない
    1. よくある失敗
  10. ハマりポイント8：Android StudioのFlutterプラグインを入れていない
    1. よくある失敗
  11. ハマりポイント9：flutter pub get を忘れる
    1. よくある失敗
  12. ハマりポイント10：flutter clean に頼りすぎる
    1. flutter clean が効きやすいケース
    2. flutter clean では解決しないケース
  13. ハマりポイント11：iOS SimulatorとAndroid Emulatorで確認できることが違う
    1. よくある失敗
  14. ハマりポイント12：iOS実機ビルドで署名エラーになる
    1. よくある失敗
  15. ハマりポイント13：Android実機で認識されない
    1. よくある失敗
  16. ハマりポイント14：Hot ReloadとHot Restartを混同する
    1. Hot Reloadで反映されやすいもの
    2. Hot Restartが必要になりやすいもの
  17. ハマりポイント15：古い記事の手順をそのまま使ってしまう
  18. 環境構築で使う基本コマンドまとめ
  19. 環境構築のおすすめ手順
  20. 1. Flutter SDKを入れる
  21. 2. flutter doctor を実行する
  22. 3. Android Studioを入れる
  23. 4. Androidライセンスに同意する
  24. 5. Xcodeを入れる
  25. 6. CocoaPodsを入れる
  26. 7. VS CodeまたはAndroid StudioのFlutterプラグインを入れる
  27. 8. サンプルアプリを起動する
  28. 環境構築チェックリスト
  29. まとめ

Flutter環境構築は、なぜハマりやすいのか

Flutterの環境構築がハマりやすい理由は、単純にインストールするものが多いからです。

Flutter公式ドキュメントでも、Flutter SDKをインストールするだけでなく、開発対象のプラットフォームに応じて初期設定を行う流れになっています。VS Codeを使ったクイックスタートや、SDKを手動でセットアップする方法も用意されています。(Flutter ドキュメント)

たとえば、iOSアプリもAndroidアプリも作りたい場合、最低でも次のようなものが関係します。

Flutter SDK
Dart SDK
Android Studio
Android SDK
Android Emulator
Xcode
iOS Simulator
CocoaPods
VS Code または Android Studio
Flutter / Dartプラグイン

つまり、Flutter環境構築は「Flutterだけ入れれば終わり」ではありません。

iOS向けにはXcodeやCocoaPodsが必要になり、Android向けにはAndroid StudioやAndroid SDKの設定が必要になります。

まず確認すべきは flutter doctor

Flutterの環境構築で最初に覚えるべきコマンドは、flutter doctor です。

flutter doctor は、Flutter開発に必要な環境がそろっているかをチェックしてくれるコマンドです。

flutter doctor

このコマンドを実行すると、Flutter SDK、Android toolchain、Xcode、Chrome、Android Studio、接続デバイスなどの状態を確認できます。

初心者がやりがちなのは、エラー文を読まずに何となく再インストールを繰り返すことです。

しかし、flutter doctor は基本的に「何が足りないか」を教えてくれます。

たとえば、次のようなメッセージが出ます。

Android toolchain - develop for Android devices
Xcode - develop for iOS and macOS
CocoaPods not installed
Android license status unknown

このような表示を見て、1つずつ潰していくのが環境構築の基本です。

Flutter公式のCLIリファレンスでも、flutter コマンドは開発者やIDEがFlutterとやり取りするためのコマンドであり、プロジェクト作成・解析・テスト・実行などに使うものとして説明されています。(Flutter ドキュメント)

ハマりポイント1：Flutter SDKのパスが通っていない

最初によくあるのが、Flutter SDKをダウンロードしたのに、flutter コマンドが使えないパターンです。

たとえば、ターミナルで次のように表示されます。

zsh: command not found: flutter

これは、Flutter SDKの bin ディレクトリにPATHが通っていない可能性があります。

Flutter SDKを配置しただけでは、ターミナルから flutter コマンドを見つけられないことがあります。

macOSでzshを使っている場合は、たとえば .zshrc に次のような設定を追加します。

export PATH="$PATH:$HOME/development/flutter/bin"

設定後は、ターミナルを再起動するか、次を実行します。

source ~/.zshrc

その後、次のコマンドで確認します。

flutter --version

よくある失敗

Flutter SDKをダウンロードしただけで満足している
PATH設定をしていない
.zshrcではなく.bash_profileに書いていて反映されていない
ターミナルを再起動していない
Flutter SDKの配置場所を後から移動してPATHがずれている

Flutter SDKの場所は、あとから変更しない方が安全です。

ハマりポイント2：Android Studioを入れたのにAndroid SDKが足りない

Androidアプリを開発する場合、Android Studioをインストールするだけでは不十分なことがあります。

Android SDK、SDK Platform、Build Tools、Command-line Tools、エミュレーターなどが正しく入っている必要があります。

Flutter公式のAndroidセットアップでは、Android StudioのSDK Managerを開き、SDK Platformsタブで必要なAndroid SDK Platformを確認する流れが説明されています。現在の公式ドキュメントでは、API Level 36のSDK Platformが選択されているか確認する手順が示されています。(Flutter ドキュメント)

Android Studioで確認する場所は、主に次の通りです。

Android Studio
↓
Settings / Preferences
↓
Languages & Frameworks
↓
Android SDK

または、

Tools
↓
SDK Manager

で確認できます。

よくある失敗

Android Studioだけ入れてSDKを入れていない
SDK Platformが足りない
Android SDK Command-line Toolsが入っていない
Android Emulatorが入っていない
SDKの場所をFlutterが認識していない

flutter doctor でAndroid toolchainにエラーが出る場合は、まずAndroid SDKのインストール状況を確認しましょう。

ハマりポイント3：Androidライセンスに同意していない

Android SDKを入れていても、ライセンスに同意していないと flutter doctor でエラーになることがあります。

その場合は、次のコマンドを実行します。

flutter doctor --android-licenses

表示されるライセンスに同意していきます。

よくある失敗

Android SDKは入っているのにdoctorが通らない
ライセンス同意をしていない
途中で入力を止めている
別ユーザーでSDKを入れていて権限がずれている

Android関連で flutter doctor が通らない場合、SDK不足とライセンス未同意はかなりよくある原因です。

ハマりポイント4：Android Emulatorが起動しない

FlutterアプリをAndroidで動かすには、実機かエミュレーターが必要です。

Android StudioからVirtual Device Managerを開き、仮想デバイスを作成します。

Android Studio
↓
Tools
↓
Device Manager
↓
Create device

ただし、エミュレーターはPC環境によってハマることがあります。

よくある失敗

エミュレーターが重すぎる
仮想化支援機能が無効になっている
Apple Silicon Macで適切なイメージを選んでいない
古いAndroidイメージを使っている
ストレージ不足で起動できない

Macの場合、Apple SiliconかIntel Macかによって選ぶべきシステムイメージが変わることがあります。

開発効率だけを考えるなら、Android実機をUSB接続して確認する方が楽な場合もあります。

ハマりポイント5：Xcodeを入れたのにiOSビルドできない

iOSアプリをFlutterで開発する場合、Xcodeが必要です。

ただし、Xcodeをインストールしただけで終わりではありません。

次のような設定が必要になることがあります。

Xcodeの初回起動
追加コンポーネントのインストール
Command Line Toolsの設定
iOS Simulatorのインストール
ライセンス同意

Xcodeをインストールしたら、一度Xcodeを起動して初期セットアップを完了させましょう。

また、コマンドラインツールの選択が必要な場合があります。

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Xcodeのライセンス同意が必要な場合は、次のように実行します。

sudo xcodebuild -license

よくある失敗

Xcodeをインストールしただけで起動していない
Command Line Toolsが別のものを向いている
Xcodeのライセンスに同意していない
iOS Simulatorが入っていない
macOSとXcodeのバージョンが合っていない

iOS開発では、FlutterよりもXcode側の設定で詰まることがよくあります。

ハマりポイント6：CocoaPodsが入っていない

iOS向けにFlutterプラグインを使う場合、CocoaPodsが必要になることがあります。

Flutter公式のmacOS開発セットアップでは、ネイティブmacOSコードを使うFlutterプラグインをサポートするために、最新のCocoaPodsをインストールするよう案内されています。iOS開発でも、プラグインのネイティブ側依存関係を扱う場面でCocoaPodsが関係します。(Flutter ドキュメント)

CocoaPodsがない場合、次のようなエラーが出ることがあります。

CocoaPods not installed.
Skipping pod install.

インストール方法はいくつかありますが、環境によってはRubyやgemの権限でハマることがあります。

sudo gem install cocoapods

または、Homebrewを使う方法もあります。

brew install cocoapods

インストール後は、次を確認します。

pod --version

よくある失敗

CocoaPodsが入っていない
podコマンドにPATHが通っていない
Rubyの権限でインストールに失敗する
Apple Silicon Macでgem周りがうまくいかない
Podfile.lockやPodsが壊れている

iOSビルドがうまくいかない場合、次のコマンドを試すこともあります。

cd ios
pod install

状態が壊れている場合は、次のようにクリーンアップすることもあります。

flutter clean
flutter pub get
cd ios
pod install

ただし、むやみに削除する前に、エラー内容を確認しましょう。

ハマりポイント7：VS CodeにFlutter拡張を入れていない

Flutter開発では、VS Codeを使う人も多いです。

しかし、VS Code本体を入れただけではFlutter開発が快適にはなりません。

Flutter公式ドキュメントでは、VS CodeでFlutter開発をするにはFlutter extensionをインストールする流れが説明されており、Flutter extensionを入れるとDart extensionもインストールされると案内されています。(Flutter ドキュメント)

必要なのは主に次の拡張です。

Flutter
Dart

インストール後、VS Codeでコマンドパレットを開いて確認します。

Cmd + Shift + P
↓
Flutter: New Project

これが表示されれば、Flutter拡張が認識されています。

よくある失敗

VS Codeだけ入れてFlutter拡張を入れていない
Dart拡張が無効になっている
Flutter SDKの場所をVS Codeが認識していない
プロジェクトを正しいフォルダで開いていない

VS Codeで補完が効かない、デバッグ実行できない場合は、まず拡張とFlutter SDKの認識状況を確認しましょう。

ハマりポイント8：Android StudioのFlutterプラグインを入れていない

Android StudioでFlutter開発をする場合も、Flutterプラグインが必要です。

Flutter公式ドキュメントでは、Android StudioまたはIntelliJでFlutterプラグインをインストールする手順として、Settings > Plugins > Marketplaceで「Flutter」を検索し、インストール後に再起動する流れが説明されています。(Flutter ドキュメント)

よくある失敗

Android Studioだけ入れてFlutterプラグインを入れていない
Dartプラグインが無効
Flutter SDKパスが未設定
Android Studioの再起動をしていない

Android StudioはAndroid SDK管理にも使うため、VS Code派でもインストールしておくことが多いです。

ハマりポイント9：flutter pub get を忘れる

Flutterプロジェクトでは、pubspec.yaml に依存パッケージを書きます。

パッケージを追加したら、次のコマンドが必要です。

flutter pub get

VS CodeやAndroid Studioが自動実行してくれる場合もありますが、依存関係がうまく解決されていないと、次のようなエラーが出ます。

Target of URI doesn't exist
Package not found
Undefined class

よくある失敗

pubspec.yamlを編集しただけでpub getしていない
インデントを間違えている
dependenciesとdev_dependenciesを間違えている
バージョン制約が衝突している

pubspec.yaml はYAMLなので、インデントミスにも注意が必要です。

悪い例です。

dependencies:
flutter:
  sdk: flutter

正しくはこうです。

dependencies:
  flutter:
    sdk: flutter

Flutter初心者は、Dartコードより先に pubspec.yaml のインデントでハマることがあります。

ハマりポイント10：flutter clean に頼りすぎる

Flutterでビルドエラーが出たとき、よく使われるのが次のコマンドです。

flutter clean

その後、次を実行します。

flutter pub get

確かに、キャッシュやビルド成果物が壊れているときには有効です。

しかし、何でもかんでも flutter clean すればよいわけではありません。

flutter clean が効きやすいケース

ビルドキャッシュが壊れている
古い生成物が残っている
パッケージ変更後に挙動がおかしい
iOS/Androidのビルド成果物が不整合を起こしている

flutter clean では解決しないケース

SDKが足りない
Xcodeの設定が間違っている
AndroidManifest.xmlが間違っている
Info.plistが間違っている
依存パッケージのバージョンが衝突している
CocoaPodsが入っていない

flutter clean は便利ですが、根本原因を見ずに実行し続けると、ただ時間を消費します。

ハマりポイント11：iOS SimulatorとAndroid Emulatorで確認できることが違う

シミュレーターやエミュレーターは便利ですが、実機と同じではありません。

特に次の機能は、実機確認が重要です。

カメラ
位置情報
通知
Bluetooth
マイク
Apple Watch連携
生体認証
アプリ内課金
広告
バックグラウンド処理

Flutter環境構築の段階では、まずシミュレーターやエミュレーターで動けば十分ですが、本格的にアプリを作るなら、早めに実機確認できる状態にしておくべきです。

よくある失敗

エミュレーターでは動いたのに実機で動かない
通知がシミュレーターでは確認できない
位置情報の精度が実機と違う
iOS実機ビルドで署名エラーになる
Android実機でUSBデバッグが無効

環境構築が終わったら、可能であればiPhone実機とAndroid実機の両方で起動確認しておくと安心です。

ハマりポイント12：iOS実機ビルドで署名エラーになる

iOS実機でFlutterアプリを動かす場合、Apple IDや署名設定が関係します。

Xcodeで ios/Runner.xcworkspace を開き、Signing & Capabilitiesを確認することがあります。

ios/Runner.xcworkspace
↓
Runner
↓
Signing & Capabilities
↓
Teamを設定

よくある失敗

Runner.xcodeprojを開いている
Runner.xcworkspaceを開いていない
Teamが未設定
Bundle Identifierが重複している
Apple IDでサインインしていない
Provisioning Profileが作られていない

CocoaPodsを使うFlutterプロジェクトでは、Xcodeで開くときに Runner.xcodeproj ではなく Runner.xcworkspace を開く必要があるケースがあります。

iOS実機ビルドでは、FlutterというよりXcodeの署名設定で詰まることが多いです。

ハマりポイント13：Android実機で認識されない

Android実機でFlutterアプリを動かすには、端末側の開発者向けオプションとUSBデバッグを有効にする必要があります。

確認コマンドは次です。

flutter devices

または、

adb devices

よくある失敗

USBデバッグが無効
端末側で接続許可をしていない
USBケーブルが充電専用
Android SDK Platform-Toolsが入っていない
端末メーカーのドライバが必要

Android実機が認識されない場合、ケーブルを変えるだけで解決することもあります。

ハマりポイント14：Hot ReloadとHot Restartを混同する

Flutterの魅力の1つがHot Reloadです。

Flutter公式ドキュメントでは、Hot Reloadは更新したソースコードをDartランタイムに注入し、FlutterフレームワークがWidgetツリーを再構築することで、変更を素早く確認できる機能だと説明されています。(Flutter ドキュメント)

ただし、すべての変更がHot Reloadで反映されるわけではありません。

Hot Reloadで反映されやすいもの

UIの文言変更
色の変更
レイアウト調整
Widgetのbuild内の変更

Hot Restartが必要になりやすいもの

main関数周辺の変更
初期化処理の変更
状態の初期値変更
依存関係の追加
ネイティブ設定の変更

さらに、次のような場合はアプリの再ビルドが必要になることがあります。

Info.plistを変更した
AndroidManifest.xmlを変更した
Podfileを変更した
ネイティブプラグインを追加した
アプリの権限設定を変更した

Hot Reloadで反映されないからといって、すぐにバグだと判断しない方がよいです。

ハマりポイント15：古い記事の手順をそのまま使ってしまう

Flutter環境構築の記事は多くあります。

しかし、Flutter、Dart、Android Studio、Xcode、CocoaPodsは更新が早いです。

数年前の記事の手順をそのまま実行すると、現在の環境ではうまくいかないことがあります。

特に注意したいのは次の情報です。

Flutter SDKのインストール方法
Android SDKのAPIレベル
Xcodeの必要バージョン
CocoaPodsのインストール方法
Gradleのバージョン
Kotlinのバージョン
targetSdkVersion

環境構築では、まず公式ドキュメントを優先しましょう。

Flutter公式ドキュメントは、インストール方法、Androidセットアップ、VS Code、Android Studioなどの設定をそれぞれ案内しています。(Flutter ドキュメント)

個人ブログやQiita、Zennの記事は、公式を見たうえで補助的に使うのがおすすめです。

環境構築で使う基本コマンドまとめ

Flutter環境構築でよく使うコマンドをまとめます。

flutter --version

Flutter SDKのバージョン確認。

flutter doctor

開発環境の診断。

flutter doctor -v

より詳細な診断。

flutter doctor --android-licenses

Android SDKライセンスへの同意。

flutter devices

接続されているデバイス確認。

flutter create my_app

新規Flutterプロジェクト作成。

flutter pub get

依存パッケージ取得。

flutter run

アプリ起動。

flutter clean

ビルド成果物の削除。

環境構築のおすすめ手順

初心者は、次の順番で進めると比較的ハマりにくいです。

1. Flutter SDKを入れる

まずFlutter SDKをインストールし、PATHを通します。

確認します。

flutter --version

2. flutter doctor を実行する

flutter doctor

ここで出たエラーを1つずつ対応します。

3. Android Studioを入れる

Android Studioをインストールし、Android SDK、Command-line Tools、Emulatorを確認します。

4. Androidライセンスに同意する

flutter doctor --android-licenses

5. Xcodeを入れる

iOS開発をする場合はXcodeをインストールし、初回起動とライセンス同意を済ませます。

6. CocoaPodsを入れる

iOSでプラグインを使う場合に備えて、CocoaPodsを入れます。

pod --version

7. VS CodeまたはAndroid StudioのFlutterプラグインを入れる

VS CodeならFlutter拡張、Android StudioならFlutterプラグインをインストールします。

8. サンプルアプリを起動する

flutter create sample_app
cd sample_app
flutter run

ここまでできれば、最低限のFlutter開発環境は整っています。

環境構築チェックリスト

最後に、チェックリストとしてまとめます。

Flutter SDKをインストールした
flutterコマンドにPATHが通っている
flutter doctorを実行した
Android Studioをインストールした
Android SDKをインストールした
Android SDK Command-line Toolsを入れた
Android EmulatorまたはAndroid実機を用意した
Androidライセンスに同意した
Xcodeをインストールした
Xcodeを初回起動した
Xcode Command Line Toolsを設定した
CocoaPodsをインストールした
VS CodeまたはAndroid StudioにFlutterプラグインを入れた
flutter devicesで端末を認識できる
flutter createしたサンプルアプリを起動できる

このチェックリストを上から順に確認すると、どこで詰まっているかを切り分けやすくなります。

まとめ

Flutter開発の環境構築は、初心者が最初につまずきやすいポイントです。

Flutter自体は便利ですが、実際にはFlutter SDKだけでなく、Android Studio、Android SDK、Xcode、CocoaPods、VS CodeやAndroid Studioのプラグインなど、複数のツールが関係します。

特にハマりやすいのは次のポイントです。

PATHが通っていない
Android SDKが足りない
Androidライセンスに同意していない
Xcodeの初期設定が終わっていない
CocoaPodsが入っていない
Flutterプラグインを入れていない
実機やエミュレーターが認識されない
Hot ReloadとHot Restartを混同している
古い記事の手順をそのまま使っている

環境構築で詰まったら、まずは flutter doctor を実行しましょう。

そして、表示されたエラーを1つずつ潰していくのが一番確実です。

Flutter環境構築は最初こそ大変ですが、一度整えば、iOS・Androidの両方に対応したアプリ開発をかなり効率よく進められます。

コメント

タイトルとURLをコピーしました