FlutterでiOSアプリを実機ビルドするときの注意点

この記事の最終更新日: 2026年5月23日

FlutterでiOSアプリを開発していると、最初はiOSシミュレーターで動作確認することが多いと思います。

しかし、実際にアプリをリリースするなら、iPhone実機での動作確認はほぼ必須です。

シミュレーターでは動いていても、実機では次のような問題が出ることがあります。

通知が想定通り届かない
位置情報の精度や許可まわりが違う
カメラやマイクが実機でしか確認できない
Apple Watch連携が確認しづらい
署名エラーでビルドできない
iPhone側でDeveloper Modeが有効になっていない

Flutterはクロスプラットフォーム開発を楽にしてくれますが、iOS実機ビルドではXcode、署名、証明書、Provisioning Profile、端末設定など、iOSネイティブ開発の知識も必要になります。

この記事では、FlutterでiOSアプリを実機ビルドするときの注意点を初心者向けに整理します。

FlutterのiOS実機ビルドにはXcodeが必要

FlutterでiOSアプリを実機ビルドするには、Xcodeが必要です。

Flutter公式ドキュメントでも、Xcodeを使うことでFlutterアプリをiOS実機またはiOSシミュレーターで実行できると説明されています。また、iOS向けの開発環境ではXcodeのインストール、Command Line Toolsの設定、ライセンス同意、iOSプラットフォームサポートのダウンロード、CocoaPodsのインストールなどが案内されています。(Flutter ドキュメント)

まずは、次のコマンドで環境を確認します。

flutter doctor

詳細まで見たい場合は、次です。

flutter doctor -v

ここで、XcodeやCocoaPodsにエラーが出ている場合は、先にそこを解消する必要があります。

注意点1：Xcode Command Line Toolsを正しく設定する

Xcodeをインストールしただけでは、Flutterが正しいXcodeを参照できていない場合があります。

Flutter公式ドキュメントでは、インストールしたXcodeのCommand Line Toolsを設定するために、次のコマンドが案内されています。(Flutter ドキュメント)

sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'

Xcodeを複数バージョン入れている場合や、過去にXcode betaを使っていた場合は、Flutterが意図しないXcodeを見に行っていることがあります。

確認するには、次のコマンドを使います。

xcode-select -p

想定外のパスになっている場合は、正しいXcodeへ切り替えましょう。

注意点2：Xcodeのライセンスに同意しておく

Xcodeを入れた直後やアップデート後は、ライセンス同意が必要になることがあります。

Flutter公式ドキュメントでも、Xcodeのセットアップ後に次のコマンドでライセンスを確認し、同意する手順が案内されています。(Flutter ドキュメント)

sudo xcodebuild -license

ライセンスに同意していないと、Flutter側ではなくXcode側のエラーとしてビルドに失敗することがあります。

注意点3：CocoaPodsを入れておく

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

Flutter公式ドキュメントでは、ネイティブiOS/macOSコードを使うFlutterプラグインをサポートするために、最新のCocoaPodsをインストールするよう案内されています。(Flutter ドキュメント)

CocoaPodsが入っているか確認します。

pod --version

入っていない場合は、環境に応じてインストールします。

sudo gem install cocoapods

または、Homebrewを使う場合は次です。

brew install cocoapods

iOSビルドで次のようなエラーが出る場合、CocoaPodsまわりが原因のことがあります。

CocoaPods not installed
pod install failed
Unable to find a specification

その場合は、次のように再取得することがあります。

flutter clean
flutter pub get
cd ios
pod install

ただし、毎回 flutter clean に頼るのではなく、エラー内容を確認して原因を切り分けることが大切です。

注意点4：実機をMacに接続して「信頼」する

iPhone実機でビルドするには、まずiPhoneをMacに接続します。

Flutter公式ドキュメントでは、iOS実機をUSBでMacに接続し、初回接続時に表示される「Trust this computer?」ダイアログで信頼する手順が案内されています。(Flutter ドキュメント)

手順は次の通りです。

iPhoneをMacに接続する
↓
iPhone側に「このコンピュータを信頼しますか？」が出る
↓
「信頼」をタップする
↓
必要に応じてパスコードを入力する

接続後、Flutterが端末を認識しているか確認します。

flutter devices

ここにiPhoneが表示されない場合は、次を確認します。

USBケーブルが充電専用ではないか
iPhone側で信頼を押したか
Mac側で端末が認識されているか
XcodeのDevices and Simulatorsに表示されるか

注意点5：iPhone側でDeveloper Modeを有効にする

iOS実機で開発用アプリを動かすには、Developer Modeが必要です。

Flutter公式ドキュメントでも、Appleは悪意あるソフトウェアから保護するため、実機側でDeveloper Modeを有効にする必要があると説明しています。手順として、iPhoneの「Settings > Privacy & Security > Developer Mode」から有効化し、端末を再起動してからDeveloper Modeをオンにする流れが案内されています。(Flutter ドキュメント)

手順は次のような流れです。

設定
↓
プライバシーとセキュリティ
↓
デベロッパモード
↓
オンにする
↓
iPhoneを再起動
↓
確認ダイアログでオンにする

Developer Modeを有効にしていないと、ビルド自体は通っても実機で起動できないことがあります。

注意点6：Apple ID・証明書・署名の理解が必要

iOS実機ビルドで最もつまずきやすいのが署名まわりです。

Flutter公式ドキュメントでは、物理iOSデバイスにアプリを送るには、Macとデバイスの信頼関係に加えて、署名済みの開発者証明書をデバイスへアップロードする必要があると説明されています。また、実機テストだけなら無料の個人Apple Developerアカウントでも動作するとされています。(Flutter ドキュメント)

ここで出てくるのが、次のような用語です。

Apple ID
Apple Developer Account
Signing Certificate
Provisioning Profile
Bundle Identifier
Development Team

初心者にとってはかなりわかりにくいですが、ざっくり言うと次のような役割です。

実機ビルドでは、このあたりが正しく設定されていないと失敗します。

注意点7：Runner.xcworkspace を開く

FlutterのiOSプロジェクトをXcodeで開くときは、基本的に次のコマンドを使います。

open ios/Runner.xcworkspace

Flutter公式のiOSリリース手順でも、Xcodeで設定を確認する際は、Flutterプロジェクトディレクトリから open ios/Runner.xcworkspace を実行して、Runnerターゲットを選択する流れが案内されています。(Flutter ドキュメント)

初心者がよく間違えるのが、次を開いてしまうことです。

ios/Runner.xcodeproj

CocoaPodsを使っているプロジェクトでは、Runner.xcworkspace を開く必要があります。

間違って Runner.xcodeproj を開くと、依存関係が正しく読み込まれず、ビルドエラーにつながることがあります。

注意点8：Signing & CapabilitiesでTeamを設定する

Xcodeで Runner.xcworkspace を開いたら、署名設定を確認します。

Runner
↓
TARGETS の Runner
↓
Signing & Capabilities
↓
Teamを選択
↓
Automatically manage signingを有効にする

Flutter公式ドキュメントでは、XcodeのSigning & Capabilitiesタブで Automatically manage signing を確認し、通常はデフォルトで有効になっていれば十分だと説明されています。また、Team には登録済みのApple Developerアカウントに紐づくチームを選択するよう案内されています。(Flutter ドキュメント)

初心者の場合は、まず Automatically manage signing を有効にして、Xcodeに自動で署名設定を管理させるのがおすすめです。

ただし、チーム開発や複雑なCapabilitiesを使う場合は、手動管理が必要になることもあります。

注意点9：Bundle Identifierをユニークにする

iOSアプリには、Bundle Identifierがあります。

たとえば、次のような形式です。

com.example.myapp

Flutter公式ドキュメントでは、すべてのiOSアプリにはAppleに登録される一意のBundle IDが関連付けられていると説明されています。App Store Connectへ登録する場合も、Bundle IDの登録とアプリレコードの作成が必要です。(Flutter ドキュメント)

実機ビルド時にも、Bundle Identifierが他のアプリと重複していたり、署名設定と合っていなかったりするとエラーになります。

Flutter新規プロジェクトの初期値に近いまま、

com.example.アプリ名

のような設定を使っている場合は、自分のドメインや識別子に変更しましょう。

例です。

com.yourname.sampleapp
com.examplecompany.productname

個人開発なら、自分の所有ドメインを逆順にした形式にすると管理しやすいです。

注意点10：iOS Deployment Targetを確認する

Flutter公式ドキュメントでは、XcodeのBuild Settings内にある iOS Deployment Target はアプリが対応する最小iOSバージョンであり、FlutterはiOS 13以降をサポートすると説明されています。また、アプリやプラグイン内のObjective-C/SwiftコードがiOS 13より新しいAPIを使う場合は、それに合わせてDeployment Targetを上げる必要があるとされています。(Flutter ドキュメント)

確認場所は次の通りです。

Xcode
↓
Runner target
↓
Build Settings
↓
iOS Deployment Target

たとえば、使っているFlutterプラグインが特定のiOSバージョン以上を要求する場合、Deployment Targetが低すぎるとビルドエラーになることがあります。

注意点11：flutter run とXcode実行の違いを理解する

Flutterアプリを実機で起動する方法は、主に2つあります。

flutter run

または、XcodeからRunボタンで実行します。

通常の開発では flutter run で十分です。

flutter devices
flutter run

ただし、署名設定やCapabilitiesの確認、iOSネイティブ設定の調整、実機ビルドエラーの詳細確認をしたい場合は、Xcodeで開いて確認した方がわかりやすいことがあります。

特に次のような場合は、Xcodeを見た方が早いです。

Signing & Capabilitiesのエラー
Provisioning Profileのエラー
Bundle Identifierのエラー
Capabilities不足
Info.plistまわりの問題
実機起動時のネイティブログ確認

Flutterだけで完結しようとせず、iOS実機ビルドではXcodeも使う前提で考えるとよいです。

注意点12：実機ビルドではシミュレーターと違う問題が出る

iOSシミュレーターでは問題なく動いていても、実機で初めて問題が見つかることがあります。

代表的なのは次のようなものです。

カメラ
マイク
位置情報
通知
Bluetooth
Apple Watch連携
生体認証
バックグラウンド処理
実機のパフォーマンス
画面サイズやノッチ
バッテリー消費

Flutter公式ドキュメントでも、iOSシミュレーターは実機よりセットアップしやすいが、実際の物理デバイスでもテストするべきだと説明されています。(Flutter ドキュメント)

特に、位置情報や通知を使うアプリでは実機確認が重要です。

シミュレーターだけで「動いた」と判断すると、リリース直前に問題が見つかることがあります。

注意点13：権限まわりは実機で確認する

iOS実機ビルドでは、権限ダイアログの出方を必ず確認しましょう。

たとえば、次の権限です。

カメラ
マイク
写真
位置情報
通知
Bluetooth
ヘルスケア
モーション

Flutter側ではパッケージを入れただけでも、iOS側では Info.plist の説明文が必要になることがあります。

たとえば、カメラなら次のようなキーが必要です。

<key>NSCameraUsageDescription</key>
<string>写真を撮影するためにカメラを使用します。</string>

位置情報なら、用途に応じて説明文が必要です。

<key>NSLocationWhenInUseUsageDescription</key>
<string>現在地を表示するために位置情報を使用します。</string>

権限説明文が不十分だと、ユーザーに不信感を与えたり、審査で問題になったりする可能性があります。

注意点14：Apple Developer Programが必要になる場面を理解する

iOS実機でテストするだけなら、無料の個人Apple Developerアカウントでも使えるとFlutter公式ドキュメントに説明されています。一方、App Storeへデプロイする場合は、Apple Developer Programへのアップグレードが必要です。(Flutter ドキュメント)

つまり、目的によって必要なアカウントが変わります。

個人開発で最初に自分のiPhoneで確認するだけなら無料アカウントから始めてもよいですが、リリースを考えているなら有料のApple Developer Programが必要になります。

注意点15：手動Provisioning Profileにハマることがある

初心者は基本的にXcodeの自動署名を使うのがおすすめです。

ただし、チーム開発や特殊なCapabilitiesを使う場合、手動でProvisioning Profileを作ることがあります。

Apple公式ドキュメントでは、手動署名をする場合はDevelopment Provisioning Profileが必要であり、作成前にApp ID、開発証明書、登録済みデバイスが必要だと説明されています。また、自動署名を使う場合はXcodeがDevelopment Provisioning Profileを管理します。(Apple Developer)

手動で作る場合の流れは、ざっくり次のようになります。

App IDを作る
↓
開発証明書を作る
↓
実機デバイスを登録する
↓
Provisioning Profileを作る
↓
Xcodeで選択する

初心者のうちは、この流れを手動で管理するとかなりハマりやすいです。

まずは自動署名で動かし、必要になったときだけ手動署名を検討する方がよいでしょう。

よくあるエラーと確認ポイント

1. No profiles for… were found

No profiles for 'com.example.app' were found

確認ポイントです。

Bundle Identifierが正しいか
Teamが選択されているか
Automatically manage signingが有効か
Apple IDでXcodeにログインしているか
実機が登録されているか

2. Signing for “Runner” requires a development team

Signing for "Runner" requires a development team.

確認ポイントです。

XcodeでRunner targetを開く
Signing & Capabilitiesを開く
Teamを選択する

3. Developer Mode is not enabled

確認ポイントです。

iPhone側でDeveloper Modeを有効にしたか
再起動後にTurn Onしたか

4. CocoaPods not installed

確認ポイントです。

pod --version
CocoaPodsが入っているか
cd ios && pod install が通るか

5. iPhoneが flutter devices に出てこない

確認ポイントです。

USBケーブルがデータ転送対応か
iPhone側で信頼したか
Developer Modeが有効か
Xcodeで端末が見えているか
Macを再起動してみる

実機ビルド前のチェックリスト

FlutterでiOSアプリを実機ビルドする前に、次を確認しましょう。

Flutter SDKが入っている
flutter doctorで大きなエラーがない
Xcodeが入っている
Xcode Command Line Toolsが正しい
Xcodeライセンスに同意している
iOS platform supportをダウンロードしている
CocoaPodsが入っている
iPhoneをMacに接続して信頼している
iPhone側でDeveloper Modeを有効にしている
XcodeにApple IDを登録している
Runner.xcworkspaceを開いている
Signing & CapabilitiesでTeamを選択している
Automatically manage signingが有効になっている
Bundle Identifierがユニークになっている
iOS Deployment Targetが適切
flutter devicesでiPhoneが見えている

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

実機で確認すべき項目

実機ビルドできたら、起動確認だけで終わらせず、次の項目も確認しましょう。

初回起動
ログイン
画面遷移
戻る操作
通知許可
位置情報許可
カメラ・マイク権限
実機での画面崩れ
ノッチ・SafeArea
ダークモード
通信エラー時の表示
バックグラウンド復帰
アプリ終了後の再起動
バッテリー消費

特に、通知・位置情報・バックグラウンド処理はシミュレーターだけでは判断しにくいです。

まとめ

FlutterでiOSアプリを実機ビルドするときは、Flutterの知識だけでなく、XcodeやiOSの署名まわりの理解が必要です。

特に注意したいのは、次のポイントです。

Xcode Command Line Tools
Xcodeライセンス
CocoaPods
iPhoneの信頼設定
Developer Mode
Apple ID
Signing & Capabilities
Bundle Identifier
Provisioning Profile
Info.plist

iOS実機ビルドでハマったときは、まず flutter doctor を確認し、そのうえでXcodeのSigning & Capabilities、Bundle Identifier、Team、Developer Modeを見直すのが基本です。

シミュレーターで動いていても、実機でしかわからない問題は多くあります。

FlutterでiOSアプリを作るなら、できるだけ早い段階でiPhone実機ビルドを確認しておくのがおすすめです。

daigoro

大阪のエンジニアが書いているブログ。