'Flutter/Flutter.h' file not found エラーの解決方法

iOSでFlutterアプリを実行またはビルドしようとした際に発生する 'Flutter/Flutter.h' file not found エラーは、Flutter開発者にとってよくある問題です。このエラーは、FlutterフレームワークがiOSプロジェクトに正しくリンクされていない場合に発生します。

問題の詳細

このエラーは通常、以下のような状況で発生します：

• 新しいマシンでプロジェクトを初めて実行しようとしたとき
• プラグインを追加・更新した後
• Flutter SDKやCocoaPodsのバージョンを変更した後
• Xcodeのビルド設定を変更した後

エラーメッセージは、さまざまなプラグイン（vibration、url_launcher、shared_preferencesなど）から報告されることが多く、根本的な原因はFlutterフレームワークがiOSプロジェクトで正しく認識されていないことにあります。

解決方法

以下に、効果的な解決策を優先順位に従って紹介します。

1. 基本的なクリーンと再ビルド

まずは最もシンプルな方法から試してみましょう：

flutter clean
flutter pub get
cd ios
pod install --repo-update
cd ..
flutter run

2. Flutter pubキャッシュの修復

パッケージキャッシュに問題がある場合、以下のコマンドで修復できます：

flutter pub cache repair
flutter clean
flutter pub get
flutter run

3. iOSフォルダの再生成

iOSプロジェクトファイルに問題がある場合、以下の手順で再生成します：

WARNING

この操作を行う前に、必ずiOSフォルダのバックアップを取ってください。特にInfo.plistやGoogleService-Info.plistなどの設定ファイルは重要です。

# iOSフォルダのバックアップを作成
cp -R ios ios_backup

# 既存のiOSフォルダを削除
rm -rf ios

# 新しいiOSプロジェクトを生成
flutter create .

# バックアップから必要なファイルを復元
cp ios_backup/Runner/Info.plist ios/Runner/
cp ios_backup/Runner/Assets.xcassets/ ios/Runner/Assets.xcassets/ -R
cp ios_backup/GoogleService-Info.plist ios/ 2>/dev/null || true

# 依存関係のインストール
cd ios
pod install
cd ..

# プロジェクトの実行
flutter run

4. CocoaPodsとFlutterの設定確認

Podfileの設定に問題がある場合、以下の点を確認してください：

ios/Podfile の重要な設定：

# iOSのデプロイメントターゲットを設定（12.0以上を推奨）
platform :ios, '12.0'

# 以下の行がpost_installセクションに含まれていることを確認
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
  end
end

設定変更後、以下のコマンドを実行：

cd ios
pod deintegrate
pod install --repo-update
cd ..
flutter clean
flutter run

5. Xcodeのビルド設定の確認

Xcodeで以下の設定を確認してください：

1. Runner → Build Phases → Run Script の位置確認：

   • Run Script（内容：/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" build）が Compile Sources の前にあることを確認
   • 追加のRun Script（Crashlyticsなど）がある場合、それらは最後に配置

2. Build Settings で以下の設定を確認：

   • Allow Non-modular Includes In Framework Modules: Yes
   • iOS Deployment Target: Podfileで指定したバージョンと一致していること

6. チャンネルの確認と切り替え

Flutterの開発チャンネルが原因である可能性もあります：

# 現在のチャンネルを確認
flutter channel

# 安定版チャンネルに切り替え
flutter channel stable
flutter clean
flutter pub get
flutter run

7. 特定のプラグインへの対応

一部のプラグイン（特にpermission_handler）では、特殊な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['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
        # 必要なパーミッションを有効化
        # 'PERMISSION_CAMERA=1',
        # 'PERMISSION_LOCATION=1',
      ]
    end
  end
end

予防策

今後同じ問題が発生するのを防ぐために：

1. バージョン管理: Flutter SDK、CocoaPods、プラグインのバージョンをチーム全体で統一する
2. 定期的な更新: 定期的に依存関係を更新し、互換性の問題を早期に発見する
3. ドキュメント: プロジェクトの設定と必要な手順を明確に文書化する
4. バックアップ: iOSプロジェクトに重要な変更を加える前に必ずバックアップを取る

まとめ

'Flutter/Flutter.h' file not found エラーはさまざまな原因で発生しますが、ほとんどの場合は上記の解決策のいずれかで解決できます。問題が解決しない場合は、使用しているFlutterとプラグインのバージョン互換性を確認し、特定のプラグインが問題を引き起こしていないかどうかを切り分けて調査してください。