React Native集成Sentry后iOS构建失败：PrivateSentrySDKOnly属性不存在

问题现象 #

使用CircleCI构建iOS应用时失败，报错如下：

Compiling RNSentry.m

❌  /Users/distiller/project/node_modules/@sentry/react-native/ios/RNSentry.m:107:79: property 'options' not found on object of type 'PrivateSentrySDKOnly'

    if (appIsActive && !sentHybridSdkDidBecomeActive && (PrivateSentrySDKOnly.options.enableAutoSessionTracking || PrivateSentrySDKOnly.options.enableOutOfMemoryTracking)) {
               ^


❌  /Users/distiller/project/node_modules/@sentry/react-native/ios/RNSentry.m:107:137: property 'options' not found on object of type 'PrivateSentrySDKOnly'

    if (appIsActive && !sentHybridSdkDidBecomeActive && (PrivateSentrySDKOnly.options.enableAutoSessionTracking || PrivateSentrySDKOnly.options.enableOutOfMemoryTracking)) {
                                                                              ^


❌  /Users/distiller/project/node_modules/@sentry/react-native/ios/RNSentry.m:155:39: property 'getSdkName' not found on object of type 'PrivateSentrySDKOnly'

        @"name": PrivateSentrySDKOnly.getSdkName,
                                                                                                                                        ^


❌  /Users/distiller/project/node_modules/@sentry/react-native/ios/RNSentry.m:195:34: property 'options' not found on object of type 'PrivateSentrySDKOnly'

        if (PrivateSentrySDKOnly.options.debug

Android构建正常，iOS构建失败，此前iOS构建正常，怀疑是Sentry版本问题。

环境配置 #

• 当前package.json中Sentry版本：@sentry/react-native": "4.8.0
• 项目依赖片段：

"dependencies": {
    "@react-native-async-storage/async-storage": "^1.17.4",
    "@react-native-community/cli-platform-android": "^6.3.0",
    "@sentry/react-native": "4.8.0",
    "@turf/distance": "^6.0.1",
    "axios": "^1.1.1",
    "dotenv": "^16.0.0",
    "eventing-bus": "^2.0.1",
    "jetifier": "^2.0.0",
    "lodash": "^4.17.15",
    "moment": "^2.29.3",
    "moment-timezone": "^0.5.34",
    "patch-package": "^6.4.7",
    "react": "17.0.2",
    "react-native": "0.67.4"
  }

• 本地环境：Windows 10，Node 16.15.0，React Native 0.67.4
• podfile.lock相关内容：

- RNSentry (3.4.2):
    - React-Core
    - Sentry (= 7.11.0)
  - Sentry (7.11.0):
    - Sentry/Core (= 7.11.0)
  - Sentry/Core (7.11.0)

已尝试的操作 #

1. 曾升级Sentry至4.9.0，出现其他严重问题
2. 执行npm-update升级至4.10.1，构建仍报相同错误

解决方案 #

核心问题 #

从podfile.lock可见，虽然package.json里@sentry/react-native是4.x版本，但实际安装的RNSentry是3.4.2版本，且绑定了Sentry 7.11.0，版本不匹配导致原生代码调用的API不存在。

修复步骤 #

1. 清理依赖缓存
   • 删除项目根目录下的node_modules文件夹
   • 执行npm cache clean --force（或yarn cache clean）
   • 删除iOS目录下的Podfile.lock和Pods文件夹
2. 指定兼容的Sentry Cocoa版本
   在iOS的Podfile中添加如下配置，强制指定与@sentry/react-native 4.x兼容的Sentry Cocoa版本：

   pod 'Sentry', '~> 6.29.0'
   

   （注：@sentry/react-native 4.x系列对应兼容的Sentry Cocoa版本范围是>=6.21.0 <7.0.0，6.29.0为较稳定的版本）
3. 重新安装依赖
   • 回到项目根目录执行npm install（或yarn install）
   • 进入iOS目录执行pod install --repo-update
4. 验证版本匹配
   重新查看podfile.lock，确认RNSentry版本与@sentry/react-native版本对应（4.x版本的@sentry/react-native对应RNSentry 4.x），且Sentry版本在6.x范围内

额外说明 #

• 若升级@sentry/react-native到更高版本，需参考官方文档确认对应的Sentry Cocoa版本，避免版本不兼容
• 本地react-native doctor报错Android Studio未找到，可手动检查环境变量ANDROID_STUDIO_PATH是否配置正确，该问题不影响iOS构建

内容的提问来源于stack exchange，提问作者Ted