🍎

【Apple】Flutter iOSアプリ「エラー発生時の新規プロジェクト移行」2025年12月版

に公開
Flutter
iOS
Xcode
Dart
CocoaPods
tech

FlutterのバージョンやmacOS/Xcodeをアップデートした際、Null check operator や Cycle inside Runner、backend.sh が見つからないといった、プログラムコードとは無関係な「環境エラーの沼」にハマることがあります。

数日間格闘してわかったのは、「古いプロジェクトの箱（設定ファイル群）」を直すより、「新しい箱」に中身を移すほうが圧倒的に早いということです。今回はその移行手順をまとめました。

1. プロジェクトの新規作成

移行前のプロジェクトはバックアップします。別のフォルダを用意して、VS Codeのコマンドパレット、またはターミナルでプロジェクトを新規に作成します。

コマンド例

flutter create --org com.yourdomain app_name
  • ポイント: 注意: VS Codeのコマンドパレットで作った場合、デフォルトの組織名(com.example)になっていることがあります。その場合は android/app/build.gradle の applicationId や、Xcodeの Bundle Identifier が以前のリリース時と一致しているか必ず確認してください。

2. 素材とコードの「引越し」

古いフォルダから新しいフォルダへ、以下のファイルをフォルダごと上書きコピーします。。

  1. lib/ （プログラム本体）
  2. assets/ （画像・データ）
  3. fonts/ （フォント）
  4. その他　アプリに必要なフォルダ、ファイルをコピーします。

2. pubspec.yaml の編集

新しいプロジェクトで生成された sdk や flutter_lints のバージョンはそのまま使い、以下の部分だけ旧ファイルから移植します。

  • dependencies: （使用しているパッケージリスト）
  • flutter_launcher_icons: （アイコン設定）
  • flutter_native_splash: （スプラッシュ設定）
  • assets: および fonts: のパス指定
  • その他必要な設定

3. podfileの修正

1.ios/Podfile を開き、platform :ios, '12.0' となっていることを確認します。

  1. 12.0固定スクリプト: ios/Podfile の末尾に強制固定スクリプトを貼り付けます。
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
    end
  end
end

4. 設定を反映させるためのクリーンアップ

flutter clean
flutter pub get
cd ios
rm -rf Pods
rm Podfile.lock
pod install
cd ..

5. ネイティブコードの生成（超重要）

pubspec.yaml に設定を書いただけでは、スプラッシュ画面やアイコンは反映されません。以下のコマンドを必ず実行してください。これを忘れると「画像が出ない」「アイコンがデフォルトのまま」になります。

# アイコン生成（背景透過なしの正方形画像を使用すること）
flutter pub run flutter_launcher_icons

# スプラッシュ画面生成
flutter pub run flutter_native_splash:create

6.VS Codeでデバッグ（F5)

アプリが正しく稼働することを確認します。

7. Xcodeでの最終調整とアーカイブ

ios/Runner.xcworkspace をXcodeで開き、以下の点を確認します。

  • iPad設定: iPadをサポートする場合、必ず Requires Full Screen にチェック。
  • 輸出コンプライアンス設定: Info.plist に ITSAppUsesNonExemptEncryption を追加し、NO に設定。これでアップロード時の質問をスキップできます。

準備ができたら、ターゲットを Any iOS Device (arm64) にして、Product > Archive を実行します。

ITSAppUsesNonExemptEncryption 設定手順

以下の手順で、Xcodeの Info.plist に追加してください。

  1. Xcodeでプロジェクト（Runner.xcworkspace）を開きます。
  2. 左側のファイルツリーで Runner フォルダの中にある Info （または Info.plist）を選択します。
  3. リストのどこでも良いので右クリックし、「Add Row」 を選択します。
  4. Keyの欄に ITSAppUsesNonExemptEncryption と入力します（コピー＆ペーストが確実です）。
  5. Typeが Boolean になっていることを確認し、Valueを NO に設定します。

💡 移行（引っ越し）を決断するタイミング

以下のサインが出たら、修復を諦めて「引っ越し」を選択することをおすすめします。

  1. エラーがループする: flutter clean しても Null check operator (xcode_backend.dart) 等が消えない。
  2. 環境アップデート直後: FlutterやXcodeを上げた直後に、自分のコード以外の場所でエラーが出る。
  3. パスが見つからない: backend.sh: No such file or directory のように、設定ファイルの「住所」が壊れている場合。

👩‍💻 今後のための「最強の初手」
次に別のアプリでビルドエラーが出たら、以下の順で試してみてください。

3分で終わる魔法: flutter clean → rm -rf ios/Pods → pod install

5分で終わるリセット: rm -rf ~/Library/Developer/Xcode/DerivedData/* (Xcodeの記憶喪失)

ここでダメなら「新規移行」: 悩む時間を捨てて、引っ越すのが賢明です。

Discussion