Hermes dSYM UUIDエラーの解決

発生する問題

React NativeアプリをApple App Storeに公開しようとすると、アーカイブ後に以下のエラーが発生します：

The archive did not include a dSYM for the hermes.framework with the UUIDs 
Ensure that the archive's dSYM folder includes a DWARF file for hermes.framework with the expected UUIDs.

このエラーは、Hermes JavaScriptエンジンのデバッグシンボル（dSYM）ファイルがアーカイブに含まれていない場合に表示されます。dSYMがないとクラッシュレポートの解析が困難になるため、App Storeへの提出がブロックされます。

解決手順

1. React Nativeバージョンの確認

プロジェクトのpackage.jsonファイルで使用中のReact Nativeバージョンを確認します：

{
  "dependencies": {
    "react-native": "^0.72.10" // 実際のバージョンを確認
  }
}

2. Hermesリリースのダウンロード

React Native公式のMavenリポジトリから、バージョンに対応するHermesをダウンロード： https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/

例) React Native 0.72.10の場合：

• ディレクトリ階層：react-native-artifacts/maven/com/facebook/react/react-native-artifacts/0.72.10/
• ファイル名：react-native-artifacts-0.72.10-hermes-ios-release.tar.gz

TIP

バージョン番号はプロジェクトの実際のバージョンに置き換えてください

3. ダウンロードしたファイルの展開

ターミナルで以下を実行（バージョン番号を調整）：

tar -xvzf react-native-artifacts-0.72.10-hermes-ios-release.tar.gz

4. ディレクトリへの移動

展開したフォルダ内のフレームワーク場所に移動：

cd react-native-artifacts-0.72.10-hermes-ios-release/destroot/Library/Frameworks/universal/hermes.xcframework/ios-arm64

5. dSYMファイルの生成

dsymutilコマンドでdSYMファイルを生成：

dsymutil hermes.framework/hermes -o hermes.framework.dSYM

WARNING

このコマンドはApple開発ツールに依存。Xcodeがインストールされていない場合は、先にXcodeのインストールが必要

6. dSYMの利用（3つの選択肢）

生成したdSYMファイルは次のいずれかの方法で使用：

Option 1: クラッシュレポートツールへ直接アップロード

• Sentry: sentry-cli upload-dif --project your-project hermes.framework.dSYM
• Firebase Crashlytics: Xcodeのアップロードスクリプトで処理

Option 2: Xcodeプロジェクトに手動追加

1. Xcodeプロジェクトを開く
2. プロジェクトナビゲータで右クリック → "Add Files to..."
3. hermes.framework.dSYMを追加

Option 3: ビルド設定にパス追加Build Settings → DEBUG_INFORMATION_FORMATをdwarf-with-dsymに設定し、DWARF File Locationにディレクトリパスを指定

根本原因と予防策

原因: HermesはReact Nativeに組み込まれるC++モジュールのため、iOSビルド時に自動でdSYMが生成されない

予防策:

• プロジェクトごとにdSYM生成を自動化するスクリプト作成
• react-nativeのマイナーバージョンアップ時は、必ず該当バージョンのHermesリリースを再確認
• CI/CDパイプラインにdSYM生成ステップを追加

:::success 技術的背景 dSYMファイルは、コンパイル後の機械語とソースコードを紐付けるデバッグシンボル情報です。Hermesのようなネイティブモジュールでは、クラッシュ時のスタックトレースを人間が読める形式に変換するために必須 :::

これらの手順により、App Store提出時のUUIDエラーを解決し、クラッシュ分析も可能になります。dSYM生成はアプリ公開前の必須ステップとお考えください。