Flutter 3.47 iOSアップグレード：2026年リモートMac移行チェックリスト

先に固定する移行方針

Flutter公式のリリース情報では、2026年8月21日時点でFlutter 3.47は安定版として掲載されています。また、Flutter 3.44以降は、iOSとmacOSのネイティブ依存関係をSwift Package Managerで管理する方式が標準になっています。詳しくはFlutterの安定版リリース情報とSwift Package Managerのアプリ開発者向けガイドを確認してください。

ただし、標準方式への変更は、すべてのCocoaPods設定を削除する指示ではありません。Swift Package Managerに未対応の依存関係については、FlutterがCocoaPodsへフォールバックできるため、まず依存関係ごとの対応状況を記録し、混在状態を検証可能な形で残します。

今週の作業順

移行前にプロジェクトを五つの場面へ分ける

同じFlutterアプリでも、Podfileの有無だけでは移行難易度を判定できません。次の表で該当する場面を先に分類し、各場面に異なる退出条件を設定します。

開始前には、pubspec.lock、iOS側のロックファイル、Podfile、Podfile.lock、Xcodeプロジェクト、共有Scheme、署名関連の設定、直近のビルドログを保存します。生成ファイルを一括削除するのではなく、バージョン管理上で変更前後を比較できる状態にしてください。

標準構成では差分を観察してから受け入れる

標準テンプレートに近く、独自のTargetや複雑なネイティブ変更がない場合でも、アップグレード後にXcodeプロジェクトを手作業で再構成するのは避けます。Flutterが生成または更新したファイルを確認し、移行前のコミットとの差分から、依存関係、Framework準備処理、Schemeの変更を特定します。

確認対象は次のとおりです。

• Swift Package Managerの依存関係がXcodeプロジェクトから解決されているか
• Flutter Frameworkを準備するスクリプトが、CIの非対話シェルでも実行されるか
• シミュレーター起動、実機ビルド、Release Archiveが同じ依存解決結果を使っているか
• 生成ファイルをコミットする範囲が、プロジェクトの既存ルールと一致しているか
• 共有Schemeがローカルだけに存在せず、CIのチェックアウト後にも利用できるか

Flutter 3.47への更新後、Swift Package Managerへ必ず完全移行する必要がありますか。

必ずしもそうではありません。Flutter 3.44以降の標準方式を受け入れるかどうかは、プロジェクト内のプラグインとホスト側の構成によって決めます。標準構成であっても、実機、Archive、エクスポートが通るまでは移行完了と扱わないでください。

移行前後で次のような差分を保存すると、後から「生成ファイルを戻すべきか」「依存解決だけを戻すべきか」を判断しやすくなります。

git diff -- ios/ .github/
xcodebuild -list
xcodebuild -showBuildSettings

出力そのものを成功証拠にするのではなく、Scheme名、Target名、依存パッケージ、署名設定、成果物の保存先を移行記録に転記します。

CocoaPodsを残す混合構成の判定

CocoaPodsを使うプラグインが残っていること自体は、移行失敗を意味しません。Flutter公式のSwift Package Manager資料でも、未対応の依存関係にはCocoaPodsへのフォールバックが示されています。したがって、Podfileの存在だけで「古い構成」と決めず、プラグインごとに次の情報を記録します。

• 依存関係の取得元とロック状態
• Swift Package ManagerまたはCocoaPodsのどちらで解決されたか
• ヘッダー、Framework、リソースなどのネイティブ生成物
• 実機ビルドとArchiveでのコンパイル結果
• プロジェクトが要求する最低OSバージョン

Flutter iOSプロジェクトでCocoaPodsを継続して使えますか。

対応していないプラグインがある場合は、検証済みの範囲で継続できます。ただし、依存関係の一部だけを新方式へ移し、残りをCocoaPodsで維持する場合は、DebugだけでなくRelease、Archive、署名エクスポートまで同じ構成で確認します。

判断は次の条件分岐にします。

• すべての重要プラグインがSwift Package Managerで解決でき、全FlavorのArchiveが通るなら、新方式へ段階的に移行します。
• 一部のプラグインだけが未対応で、CocoaPods併用で実機とArchiveが通るなら、二重構成を記録したうえで継続します。
• 依存解決は通ってもネイティブコンパイルや署名で失敗するなら、プラグイン置換またはアップグレード延期へ戻します。
• 旧構成の復元手順がCIで再現できないなら、本番ノードの切り替えを止めます。

Flavorと自作Targetは構成ごとに合否を出す

多Flavorプロジェクトでは、Runner のDebugビルドだけを実行しても不十分です。FlavorごとのScheme、Build Configuration、Bundle Identifier、署名設定、Flutter Framework準備処理を分けて確認します。

Flutterの複数FlavorでSwift Package Managerを検証するには、何を比較すべきですか。

各Flavorを個別に選び、依存パッケージの解決、テスト、Archive、エクスポートを同じ順序で実行します。自作Targetがある場合は、Swiftパッケージのリンク設定がデフォルトTargetだけでなく、対象Targetにも関連付けられているかをXcodeの設定とビルドログで確認します。

最低限、次の記録をFlavorごとに残します。

• 使用したSchemeとBuild Configuration
• 依存解決に関するログ
• Archiveの保存先とエクスポート結果
• 署名Identity、Provisioning Profile、Bundle Identifier
• 失敗時に旧コミットへ戻して再実行した結果

AppleのArchiveとアプリ書き出しに関する公式資料およびXcodeの配布手順に沿って、ビルド成功と配布可能な成果物を分けて扱います。

add-to-appはホスト側を起点に確認する

add-to-appでは、純粋なFlutterアプリの生成物だけを見ても判断できません。原生のiOSホストプロジェクトにあるパッケージ、Flutterモジュールの初期化、リソース配置、DebugとReleaseの設定を確認します。

Flutter add-to-appの更新後は、どの原生依存関係を点検すべきですか。

ホスト側のSwift Package Manager依存、残存するCocoaPods統合、埋め込みFramework、Flutterモジュールの検索パスを確認します。旧方式のFrameworkやPods設定を新しい統合方式の設定に、検証なしで重ねてはいけません。

Flutter公式のadd-to-app iOSプロジェクト保守ガイドを参照し、少なくとも次の経路を通します。

• ホストアプリのネイティブ画面からFlutterモジュールを起動する
• Release構成でビルドし、リソースとネイティブ依存関係を確認する
• 旧統合方式を復元して、旧コミットで再び起動できることを確認する

起動確認だけでなく、ホストアプリのArchiveとエクスポートまで実施してください。add-to-appでは、Flutter画面が表示されても、配布用構成のリンクやリソース処理だけが失敗することがあります。

リモートMacとCIノードを本番投入する条件

リモートMacを移行用ノードにする場合、GUIセッションで成功した操作をそのままCIの成功とみなさないことが重要です。SSHの非対話セッションで環境変数、証明書へのアクセス、キャッシュディレクトリ、作業ディレクトリ、再起動後のサービス復旧を確認します。

NodeMiniのリモートMac環境を検討する場合も、最初から本番構築ノードとして扱わず、既存パイプラインを複製した隔離環境で移行記録を作成してください。手元に検証用Macがない場合は、Mac miniのレンタル構成を比較するページも、必要な接続方式と運用期間を整理する材料になります。

リモートMacでFlutter iOSのArchiveと署名を受け入れるには、何を実行すべきですか。

クリーン構築、キャッシュを使った構築、実機署名、Archive、エクスポート、再起動後の再実行を分けて行います。すべてが同じ結果になる必要はありませんが、差分が説明でき、旧構成へ戻せることが合格条件です。

ssh build-node 'env | sort'
ssh build-node 'flutter --version'
ssh build-node 'xcodebuild -list'
ssh build-node './ci/build-ios.sh'

この例では、バージョン表示だけでなく、CIスクリプトが非対話SSHで最後まで完了するかを見ます。署名資格情報を平文で保存せず、Appleのチーム署名証明書の管理資料に従って、アクセス権限と復旧手順を別途記録してください。

本番切り替え前の最終判定は、次のように整理できます。

• クリーン構築とキャッシュ構築が通り、実機署名、全FlavorのArchive、エクスポートが完了しているなら切り替え候補です。
• GUIでは通るがSSHで失敗するなら、環境変数、キーチェーン、権限、キャッシュの初期化を確認し、切り替えを延期します。
• 新方式で一部プラグインが失敗し、旧CocoaPods構成は再現できるなら、二軌道を維持します。
• 旧構成の復元、ノード再起動後の再実行、成果物の保存ができないなら、本番ノードは更新しません。

既存のMac miniを常設する方式では、ハードウェアの調達、設置場所、電源、障害時の交換、外部アクセス経路をチーム側で持つ必要があります。一方、Linuxや一般的なクラウド環境ではXcode、Appleの署名環境、iOS実機向けのネイティブツールチェーンを同じ条件で用意できません。隔離検証をすぐに始めたい、またはリリース期間だけMac構築ノードが必要な場合は、NodeMiniのリモートMacを一つの選択肢として比較すると、購入前に実際のCI手順を確認できます。

長期的に同じ負荷を常時かける場合や、物理USB機器を常に接続する必要がある場合は、自社保有のMacが適しています。反対に、Flutter 3.47の移行期間だけ別ノードが必要な場合は、まず一つのリリースサイクル分を隔離環境で運用し、チェックリストが通った後にノードを維持するか、拡張するか、解放するかを決めるのが安全です。