Flutter iOSアプリのアーカイブでFlutter.framework dSYMエラーの解決法

エラーの概要

XcodeでiOSアプリをアーカイブした際、以下のエラーが発生することがあります：

The archive did not include a dSYM for the Flutter.framework with the UUIDs [4C4C**-5555-****-*****45CD327]

この問題は、Flutter.frameworkのデバッグシンボルファイル(.dSYM)がアーカイブに含まれていない場合に発生します。クラッシュレポートを正常に解析するためにはこのファイルが必須です。

主な解決方法

解決法1: Flutterを最新バージョンにアップグレード（推奨）

複数の報告で有効性が確認されている最もシンプルな解決策です。

# Flutterの安定版をアップグレード
flutter upgrade

効果

• Flutterのバグ修正が適用される
• Hermesエンジン関連の問題が解消される
• 2024~2025年の複数の報告で成功率が高い

解決法2: 手動でdSYMを生成して追加

アップグレードで解決しない場合の手動対応方法：

1. フレームワークの場所を特定

find ~/Library/Developer/Xcode/DerivedData -name "Flutter.framework" | grep -v "SourcePackages"

2. dSYMを手動生成

xcrun dsymutil -o ~/Desktop/Flutter.framework.dSYM \
  /path/to/found/Flutter.framework/Flutter

3. アーカイブに追加
   • Xcode → Window → Organizer
   • 最新のアーカイブを右クリック → "Show in Finder"
   • .xcarchive を右クリック → "Show Package Contents"
   • dSYMs フォルダに生成したファイルをコピー

解決法3: Xcodeビルドフェーズに自動生成スクリプトを追加

永続的な対策として有効です。

1. Xcodeでプロジェクトを開く
2. ターゲット → Build Phases
3. "+" → New Run Script Phase
4. スクリプトを追加:

if [ -d "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Flutter.framework" ]; then
  echo "🚧 Flutter.frameworkのdSYMを生成中..."
  dsymutil "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Flutter.framework/Flutter" \
    -o "${BUILT_PRODUCTS_DIR}/Flutter.framework.dSYM"
fi

Shorebirdユーザーの場合（解決法4）

Shorebirdを使用している場合の特別な手順:

1. Shorebirdコンソール → アプリバージョン → Artifacts
2. 「Flutter.dSYM」ファイルをダウンロード
3. 解決法2の手順でアーカイブのdSYMsフォルダにコピー

予防策とベストプラクティス

1. ビルド前のクリーンアップ

   flutter clean

2. Build Phasesの順序確認

   • Generate Hermes dSYMフェーズが存在すること
   • 順序: [CP] Embed Pods Frameworksの直後に配置

3. Hermesを使用している場合の確認スクリプト

   set -euo pipefail
   HERMES_BIN="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/hermes.framework/hermes"
   HERMES_DSYM="${DWARF_DSYM_FOLDER_PATH}/hermes.framework.dSYM"
   
   if [ -e "$HERMES_BIN" ] && [ ! -e "$HERMES_DSYM" ]; then
     echo "🛠 HermesのdSYMを生成しています..."
     /usr/bin/dsymutil "$HERMES_BIN" -o "$HERMES_DSYM"
   fi

注意点

• flutter build ios --no-codesign でビルドした場合、手動でのdSYM生成が必要
• Xcodeの「Validate」実行前に対処するのが効果的
• 古いDerivedDataに起因する問題が多いため定期的にクリーンアップを

これらの対策でUUID不一致エラーはほぼ解決されます。シンプルなアップグレードから始め、問題が解消しない場合は段階的に高度な対策を適用してください。