为什么 React Native 项目中的 dSYM 文件不再自动生成？

在 React Native 项目中，dSYM（调试符号文件）未自动生成通常是由于 构建流程配置错误、脚本缺失 或 版本兼容性问题 导致的。以下是详细原因和逐步排查方法：

1. 根本原因分析

(1) Xcode 构建设置未启用 dSYM 生成

• 问题：Xcode 的 Debug Information Format 未设置为 DWARF with dSYM File，导致调试符号未生成。
• 验证方法：
  1. 打开 Xcode → 项目 → Build Settings
  2. 搜索 Debug Information Format，确保 Release 模式为 DWARF with dSYM File
  3. 确保 Generate Debug Symbols 设为 YES

(2) Hermes 生成脚本未正确集成

• 问题：create-dsym.sh 脚本未添加到 Xcode 构建流程或路径配置错误。
• 验证方法：
  1. 打开 Xcode → Build Phases，检查是否存在 Hermes dSYM 生成脚本
  2. 确保脚本路径正确：

     HERMES_ENGINE_PATH="${PODS_ROOT}/hermes-engine"
     REACT_NATIVE_PATH="../node_modules/react-native"
     

(3) 缓存或依赖冲突

• 问题：旧版本缓存或依赖残留导致构建异常。
• 解决方案：

  rm -rf ios/build && pod deintegrate && rm -rf ~/Library/Developer/Xcode/DerivedData
  cd ios && pod install --repo-update
  

(4) Hermes 二进制文件路径不匹配

• 问题：Hermes 的二进制文件路径与脚本中配置的路径不一致。
• 验证方法：

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

---

2. 逐步排查与修复

步骤 1：检查 Xcode 构建日志

• 在 Xcode 中执行 Product → Archive
• 打开 Report Navigator，搜索 hermes 或 dSYM
• 可能的错误信息：
  • Error: Hermes dSYM generation script not found → 脚本路径错误
  • Permission denied → 脚本权限不足

步骤 2：验证脚本路径和权限

• 检查脚本是否存在：

  ls ../node_modules/react-native/scripts/hermes/create-dsym.sh
  

• 赋予执行权限：

  chmod +x ../node_modules/react-native/scripts/hermes/create-dsym.sh
  

步骤 3：手动运行 Hermes dSYM 生成脚本

HERMES_ENGINE_PATH="${PODS_ROOT}/hermes-engine"
REACT_NATIVE_PATH="../node_modules/react-native"

"$REACT_NATIVE_PATH/scripts/hermes/create-dsym.sh" \
  -i "$HERMES_ENGINE_PATH/destroot/Library/ios-arm64/hermes.framework/hermes" \
  -o "./hermes.framework.dSYM"

• 如果成功：说明脚本逻辑正确，可能是 Xcode 构建问题。
• 如果失败：检查路径或依赖版本。

步骤 4：检查 Xcode 脚本执行顺序

• 打开 Xcode → Build Phases
• 确保脚本在：
  1. 所有编译阶段之后
  2. Copy dSYMs 之前

---

3. 高级场景解决方案

场景 1：React Native 版本兼容性问题

• 某些版本（0.64~0.68）存在 Hermes dSYM 生成问题。
• 解决方案：
  • 升级到最新稳定版：

    yarn upgrade react-native@0.72.4
    

  • 回退到兼容版本：

    yarn add react-native@0.76.7 --exact
    

场景 2：M1/M2 芯片的架构问题

• Apple Silicon 设备可能因 Rosetta 兼容性导致路径错误。
• 解决方案：
  1. 在终端中运行 Xcode：

     sudo arch -x86_64 xcodebuild -scheme YourScheme -archivePath YourApp.xcarchive archive
     

  2. 为 Hermes 指定完整路径：

     HERMES_ENGINE_PATH="/opt/homebrew/lib/hermes-engine"
     

场景 3：自定义构建流程干扰

• 如果使用 Fastlane，可能覆盖了默认 dSYM 生成逻辑。
• 修复方法： 在 Fastfile 中添加 dSYM 生成：

  lane :archive do
    build_app(
      scheme: "YourApp",
      export_method: "app-store",
      include_dSYMs: true,
      xcargs: "DEBUG_INFORMATION_FORMAT='dwarf-with-dsym'"
    )
  end
  

---

4. 终极验证方法

(1) 直接检查归档文件

• 打开 .xcarchive → dSYMs 文件夹
• 如果仍缺失 hermes.framework.dSYM：

  dsymutil ${PODS_ROOT}/hermes-engine/destroot/Library/ios-arm64/hermes.framework/hermes -o hermes.framework.dSYM
  cp -R hermes.framework.dSYM /path/to/YourApp.xcarchive/dSYMs/
  

(2) 使用官方预编译 dSYM

• 下载官方 dSYM 文件：

  1. 访问 React Native Releases 页面
  2. 选择 对应版本（如 0.76.7）
  3. 下载 hermes.framework.dSYM

• 替换本地文件：

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

---

总结

dSYM 未自动生成的核心原因：

1. Xcode 配置错误（未启用 DWARF with dSYM File）。
2. Hermes dSYM 生成脚本问题（路径错误、权限不足）。
3. 缓存或依赖问题（需要清理 & 重新安装）。
4. React Native 版本兼容性问题（升级或降级）。
5. Apple Silicon 设备的架构问题（使用 arch -x86_64 运行 Xcode）。
6. Fastlane 等自定义脚本干扰。

彻底解决方案：

• 检查 Xcode 配置（Debug Information Format）。
• 验证 Hermes dSYM 生成脚本的路径和权限。
• 清理缓存并更新依赖（pod install --repo-update）。
• 手动生成 dSYM 或下载官方 dSYM 替换。