迁移到 5.x

了解如何将 SDK 升级到 5.x 版本。

React Native SDK 5.x 版本支持 Legacy（从 RN 0.65 及以上）和 New Architecture（从 RN 0.69 及以上），以及新的 React Native Gradle 插件（在 RN 0.71 中引入）。

重命名以下 Sentry.init 选项：

enableAutoPerformanceTracking 改为 enableAutoPerformanceTracing
enableOutOfMemoryTracking 改为 enableWatchdogTerminationTracking
ReactNativeTracingOptions.idleTimeout 改为 ReactNativeTracingOptions.idleTimeoutMs
ReactNativeTracingOptions.maxTransactionDuration 改为 ReactNativeTracingOptions.finalTimeoutMs

如果你使用了 TouchEventBoundary 和 accessibilityLabel，请设置以下内容：

Copied

Sentry.wrap(App, {
  touchEventBoundaryProps: { labelName: "accessibilityLabel" },
});

Sentry.captureMessage 的当前堆栈跟踪已从 event.exception 移动到 event.threads。

默认的 breadcrumb.level 是 info，值 critical 已被移除，log 在 iOS 和 Android 上已被转换为 debug。

捆绑的 sentry-cli 版本已升级到 v2.10.0。请检查你对 sentry-cli 的使用以反映重大更改。注意，upload-dsym 已被 debug-files upload 取代，并且需要提供路径。请确保检查你的 Xcode 项目中的 Upload Debug Symbols 构建步骤。命令应类似于以下示例：

Copied

# Before
../node_modules/@sentry/cli/bin/sentry-cli upload-dsym

# After
../node_modules/@sentry/cli/bin/sentry-cli debug-files upload "$DWARF_DSYM_FOLDER_PATH"

以下元数据已从 sentry-cocoa 同步到 react-native：

tags
extra
fingerprint
level
environment
breadcrumbs

同步的 fingerprint 可能会影响 Sentry 中的问题分组。React Native event.fingerprint 会与 iOS fingerprint 合并，且不会重复，RN 项会在顺序中排在前面。

sentry-cocoa 已升级到 v8.0.0，请参考相关迁移指南这里。

sentry-wizard 不会为 React Native 0.65 到 0.68 的 iOS 项目打补丁。这些版本需要手动打补丁。

最低支持的 iOS 版本已提升到 iOS 11。最低 Android API 已提升到 21。最低支持的 React Native 版本是 0.65.0。

在 4.9.0 版本中添加了一个新功能，允许在 React Native 应用的事件中发送运行时 JavaScript 依赖项。对于 Android 构建，启用此功能不需要手动步骤。对于 iOS，你需要修补 ios/$projectName.xcodeproj/project.pbxproj 文件中的 shellScript，其中 $projectName 可能是你的项目名称。为此，请查找 Bundle React Native code and images 阶段并修补 shellScript。

React Native 0.69.0 及以上版本：

Old:

Copied

shellScript = "export SENTRY_PROPERTIES=sentry.properties\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nset -e\n\nWITH_ENVIRONMENT=\"../node_modules/react-native/scripts/xcode/with-environment.sh\"\nREACT_NATIVE_XCODE=\"../node_modules/react-native/scripts/react-native-xcode.sh\"\n\n/bin/sh -c \"$WITH_ENVIRONMENT \\\"../node_modules/@sentry/cli/bin/sentry-cli react-native xcode $REACT_NATIVE_XCODE\\\"\"\n";

New:

Copied

shellScript = "export SENTRY_PROPERTIES=sentry.properties\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nset -e\n\nWITH_ENVIRONMENT=\"../node_modules/react-native/scripts/xcode/with-environment.sh\"\nREACT_NATIVE_XCODE=\"../node_modules/react-native/scripts/react-native-xcode.sh\"\n\n/bin/sh -c \"$WITH_ENVIRONMENT \\\"../node_modules/@sentry/cli/bin/sentry-cli react-native xcode $REACT_NATIVE_XCODE\\\"\"\n\n/bin/sh ../node_modules/@sentry/react-native/scripts/collect-modules.sh\n";

React Native 0.56.0 到 0.68.0：

Old:

Copied

shellScript = "export NODE_BINARY=node\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nexport SENTRY_PROPERTIES=../sentry.properties\n\n../node_modules/@sentry/cli/bin/sentry-cli react-native xcode \\\n  ../node_modules/react-native/scripts/react-native-xcode.sh\n";

New:

Copied

shellScript = "export NODE_BINARY=node\nexport EXTRA_PACKAGER_ARGS=\"--sourcemap-output $DERIVED_FILE_DIR/main.jsbundle.map\"\nexport SENTRY_PROPERTIES=../sentry.properties\n\n../node_modules/@sentry/cli/bin/sentry-cli react-native xcode \\\n  ../node_modules/react-native/scripts/react-native-xcode.sh\n\n/bin/sh ../node_modules/@sentry/react-native/scripts/collect-modules.sh\n";

有关升级到版本 7.19.0 的相关更改，请参阅 JS SDK 迁移指南。

有关升级到版本 7.16.0 的相关更改，请参阅 JS SDK 迁移指南这里和这里。

通过将 Sentry JavaScript 升级到 v7，引入了一些重大更改。要了解更多更改的内容，请查看 Sentry JavaScript 的重大更改更新日志。

通过将 Sentry Android 升级到 v6，也引入了一些重大更改。要了解更多更改的内容，请查看迁移指南。

ReactNavigationV5Instrumentation 已重命名为 ReactNavigationInstrumentation，并支持 v5 及以上版本的所有 React Navigation，包括 v6。你只需要在调用 instrumentation 构造函数的地方更改名称：

Copied

// Old
const routingInstrumentation =
  new Sentry.ReactNavigationV5Instrumentation();
// New
const routingInstrumentation = new Sentry.ReactNavigationInstrumentation();

从版本 2.x 升级到 3.x 时不需要进行任何更改，但你需要确保在 iOS 上运行 pod install 并在两个平台上重新构建你的应用程序。

当从之前的版本升级到 3.x 时，你可能会看到 event.environment 标签的值与之前版本 SDK 发送的事件不匹配。来自原生 iOS 代码的事件现在将 event.environment 标签设置为 native。更多关于这些标签的信息，请参阅事件信息指南。

重大更改仅适用于 Android，其他平台没有重大更改。

Sentry React Native 版本 2.5.0 依赖于 Sentry Android 5.0.0。请参考 Android 迁移指南以了解 Android 特定的更改。

Settings.Secure.ANDROID_ID 已被移除并替换为随机生成的 installationId。这可能会影响 Issues 页面和 Alerts 中显示的独特用户数量。如果你一直使用 Sentry.setUser(customUser) 设置自定义用户，则行为没有改变。虽然你不需要进行任何更新，但如果你想保持旧的行为，可以使用以下代码片段，该片段使用了 react-native-device-info 库。

Copied

import { Platform } from "react-native";
import DeviceInfo from "react-native-device-info";

import * as Sentry from "@sentry/react-native";

Sentry.init({
  // ...
});

// Only add the event processor on Android
if (Platform.OS === "android") {
  Sentry.addGlobalEventProcessor((event) => {
    // Get the ANDROID_ID
    const id = DeviceInfo.getUniqueId();

    // If the user does not exist, set the id to be the unique id.
    if (!event.user) {
      event.user = { id };
    }

    return event;
  });
}

我们更改了 React Navigation v5 及以上版本的路由 instrumentation 初始化方法，以避免在使用 linking 时可能出现的问题。你现在需要在传递给 NavigationContainer 的 onReady 属性中注册导航容器。

从：

Copied

// Old Functional Component Example
const App = () => {
  const navigation = React.useRef();

  React.useEffect(() => {
    routingInstrumentation.registerNavigationContainer(navigation);
  }, []);

  return <NavigationContainer ref={navigation}>...</NavigationContainer>;
};

// Old Class Component Example
class App extends React.Component {
  navigation = React.createRef();

  componentDidMount() {
    routingInstrumentation.registerNavigationContainer(navigation);
  }

  render() {
    return (
      <NavigationContainer ref={this.navigation}>...</NavigationContainer>
    );
  }
}

到：

Copied

// Functional Component Example
const App = () => {
  const navigation = React.useRef();

  return (
    <NavigationContainer
      ref={navigation}
      onReady={() => {
        // Register the navigation container with the instrumentation inside onReady
        routingInstrumentation.registerNavigationContainer(navigation);
      }}
    >
      ...
    </NavigationContainer>
  );
};

// Class Component Example
class App extends React.Component {
  navigation = React.createRef();

  render() {
    return (
      <NavigationContainer
        ref={this.navigation}
        onReady={() => {
          // Register the navigation container with the instrumentation inside onReady
          routingInstrumentation.registerNavigationContainer(navigation);
        }}
      >
        ...
      </NavigationContainer>
    );
  }
}

Sentry 最新版本的 React Native SDK 默认启用了发布健康跟踪和原生堆栈跟踪。

此版本的 SDK 使用 envelope endpoint。如果你使用的是自托管 Sentry，SDK 需要 Sentry 版本 20.6.0 及以上。如果你使用的是我们的 SaaS 产品 (sentry.io)，则不需要进行任何更改或操作。

虽然此次迁移在 React Native 方面不会对 iOS/MacOS 引入重大更改，但我们建议升级后运行 pod install。

如果你直接使用我们的 Cocoa SDK，请参考 5.x 到 6.x 的迁移指南。

在 iOS/MacOS 上，我们现在会在磁盘上缓存 envelope 中的事件。因此，在迁移过程中你可能会丢失一些缓存的事件。由于涉及的工作量较大，从 5.x 到 6.x 的迁移不会将这些缓存的事件移动到 envelopes 中。

如果你使用的是 React Native <0.60，你需要更新 MainApplication.java 中的这一行：

从（早期版本）：

Copied

import io.sentry.RNSentryPackage;

新：

Copied

import io.sentry.react.RNSentryPackage;

除了上述提到的一行更改外，迁移不应该在 React Native 方面引起重大更改。

如果你直接使用我们的 Android SDK，你应该参考其从 2.x 到 3.x 的迁移指南。

如果你是从 Sentry 的 React Native SDK 的早期版本升级，请取消链接该包以确保生成的代码更新到最新版本：

Copied

react-native unlink react-native-sentry

之后从你的 package.json 中移除 react-native-sentry：

Copied

npm uninstall react-native-sentry --save
# or
yarn remove react-native-sentry

从那里，你可以按照 @sentry/react-native 的标准安装说明进行操作。

从 5.x 迁移到 6.x

从 sentry-expo 迁移