React Native 提交至 App Store 报错 The archive did not include a dSYM for the hermes.framework 终极解决方案

React Native 0.76.7 iOS 打包提交 App Store 遇到 Hermes dSYM 缺失问题的解决方案

错误描述

在使用 React Native 0.76.7 打包 iOS 应用并提交至 App Store Connect 时，可能会遇到以下错误：

The archive did not include a dSYM for the hermes.framework with the UUIDs [370D4F3B-9105-372E-A571-E4AA5F1DCE9A].
Ensure that the archive's dSYM folder includes a DWARF file for hermes.framework with the expected UUIDs.

该错误表明归档文件（Archive）中 缺少 Hermes 引擎的调试符号文件（hermes.framework.dSYM），导致苹果无法验证二进制文件的完整性。

---

问题原因

1. Hermes dSYM 未生成
   React Native 构建流程可能未正确生成 Hermes 的调试符号文件。

2. 版本升级冲突
   从旧版本升级至 React Native 0.76.7 时，残留的构建缓存或依赖可能导致符号文件丢失。

3. 架构目录不匹配
   Hermes 的 dSYM 文件需要根据 构建目标（真机、模拟器等）放置到正确的架构目录中。

---

完整解决方案

一、检查现有 dSYM 文件

1. 定位归档文件

在 Finder 中，进入 Xcode 归档文件默认路径：

~/Library/Developer/Xcode/Archives

找到最新生成的 .xcarchive 文件，右键 → 选择“显示包内容”。

2. 验证 dSYM 是否存在

进入 dSYMs 目录，检查是否包含：

• YourApp.app.dSYM（应用自身的符号文件）
• hermes.framework.dSYM（Hermes 引擎的符号文件）

如果 hermes.framework.dSYM 缺失，请继续执行以下步骤。

---

二、处理版本升级冲突

1. 清理项目缓存

# 删除 iOS 构建目录
rm -rf ios/build

# 清理 Xcode 缓存
rm -rf ~/Library/Developer/Xcode/DerivedData

# 清理 CocoaPods 缓存
cd ios && pod deintegrate && rm -rf Pods

2. 更新依赖

# 升级 React Native 至 0.76.7
yarn up react-native@0.76.7

# 重新安装 iOS 依赖
cd ios && pod install --repo-update

---

三、生成 Hermes dSYM 文件

方案 1：通过 Xcode 构建脚本自动生成

1. 添加构建脚本
   • Xcode → 项目 Target → Build Phases → 点击 +，选择 New Run Script Phase。
   • 将以下脚本粘贴到输入框中，并命名为 Generate Hermes dSYM：

   HERMES_ENGINE_PATH="${PODS_ROOT}/hermes-engine"
   REACT_NATIVE_PATH="../node_modules/react-native"
   
   if [ -f "$REACT_NATIVE_PATH/scripts/hermes/create-dsym.sh" ]; then
     "$REACT_NATIVE_PATH/scripts/hermes/create-dsym.sh" \
       -i "$HERMES_ENGINE_PATH/destroot/Library/ios-arm64/hermes.framework/hermes" \
       -o "${DWARF_DSYM_FOLDER_PATH}/hermes.framework.dSYM"
   else
     echo "Error: Hermes dSYM 生成脚本未找到！"
   fi
   

2. 调整脚本顺序 确保 Generate Hermes dSYM 在 Copy dSYMs 之前执行。

方案 2：手动生成并集成

1. 找到 Hermes 二进制文件

${PODS_ROOT}/hermes-engine/destroot/Library/ios-arm64/hermes.framework/hermes

1. 生成 dSYM

dsymutil ${PODS_ROOT}/hermes-engine/destroot/Library/ios-arm64/hermes.framework/hermes -o hermes.framework.dSYM

1. 复制到归档文件

cp -R hermes.framework.dSYM /path/to/YourApp.xcarchive/dSYMs/

---

四、从官方 Release 下载 dSYM 文件

如果本地生成失败，可直接从 React Native 官方仓库 下载预编译的 dSYM 文件。

1. 访问 Releases 页面

在 React Native Releases 中，找到 0.76.7 版本。

2. 下载匹配架构的 dSYM

目录名称	适用场景
ios-arm64	iOS 真机
ios-arm64_x86_64-simulator	iOS 模拟器
ios-arm64_x86_64-maccatalyst	Mac Catalyst 应用
xros-arm64	Vision Pro 真机
xros-arm64_x86_64-simulator	Vision Pro 模拟器

3. 集成到项目

cp -R /path/to/downloaded/hermes.framework.dSYM /path/to/YourApp.xcarchive/dSYMs/

---

五、验证 UUID 匹配

1. 检查 dSYM 的 UUID

dwarfdump --uuid /path/to/YourApp.xcarchive/dSYMs/hermes.framework.dSYM

输出结果应包含 错误信息中的 UUID（如 370D4F3B-9105-372E-A571-E4AA5F1DCE9A）。

1. 检查 Hermes 二进制文件的 UUID

dwarfdump --uuid ${PODS_ROOT}/hermes-engine/destroot/Library/ios-arm64/hermes.framework/hermes

如果两者 UUID 不一致，需要重新生成或下载正确版本的 dSYM 文件。

---

六、重新提交至 App Store

1. 清理构建
   • Xcode → Product → Clean Build Folder
2. 生成新归档
   • Xcode → Product → Archive
3. 验证归档文件
   • Xcode Organizer → 右键最新归档 → Show in Finder → 检查 dSYMs 文件夹。
4. 提交至 App Store Connect
   • 确保一切正确后，重新提交应用。

---

总结

• 优先使用 Xcode 脚本自动生成 Hermes dSYM，确保流程标准化。
• 彻底清理缓存，避免版本升级后 dSYM 丢失。
• 官方 dSYM 下载 适用于本地生成失败或 UUID 不匹配的情况。
• 始终验证 UUID 一致性，保证符号文件正确匹配二进制文件。

通过以上步骤，可彻底解决 Hermes dSYM 缺失问题，顺利提交应用到 App Store！🚀