手动配置

了解 iOS 和 Android 的手动配置。

如果你无法(或不希望)运行 自动设置,请使用以下说明来配置你的应用程序。

安装 @sentry/react-native 包:

Copied
npm install @sentry/react-native --save

对于 iOS,Sentry SDK 包装了 React Native bundle 过程以自动上传源映射。SDK 还添加了一个新的 Xcode 构建阶段来上传调试符号,以确保你获得可读的原生崩溃堆栈跟踪。

SDK 需要访问有关设备和应用程序的某些信息以实现其基本功能。其中一些 API 被认为与隐私相关。将隐私清单添加到你的 Xcode 项目中,以确保你的应用程序符合 Apple 的指南。阅读 Apple 隐私清单 指南,了解更多关于如何添加 Sentry SDK 所需记录的信息。

在你的 ios 目录中添加一个 sentry.properties 文件。

ios/sentry.properties
Copied
defaults.url=https://sentry.io/
defaults.org=example-org
defaults.project=example-project
auth.token=sntrys_YOUR_TOKEN_HERE

我们对 React Native 构建阶段(“Bundle React Native code and images”)进行了轻微修改,从这开始:

Bundle React Native code and images
Copied
set -e

WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="../node_modules/react-native/scripts/react-native-xcode.sh"

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"

改为这:

Bundle React Native code and images
Copied
set -e

WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="../node_modules/react-native/scripts/react-native-xcode.sh"
SENTRY_XCODE="../node_modules/@sentry/react-native/scripts/sentry-xcode.sh"
BUNDLE_REACT_NATIVE="/bin/sh $SENTRY_XCODE $REACT_NATIVE_XCODE"

# RN 0.69+
/bin/sh -c "$WITH_ENVIRONMENT \"$BUNDLE_REACT_NATIVE\""

# RN 0.46 – 0.68
# /bin/sh -c "$BUNDLE_REACT_NATIVE"

要更改默认行为,在 .xcode.env 或构建阶段脚本中传递以下环境变量:

.xcode.env
Copied
export SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable source map upload

export AUTO_RELEASE=true # Automatically detect release from Xcode project
export SENTRY_CLI_EXECUTABLE="path/to/@sentry/cli/bin/sentry-cli"
export SENTRY_CLI_EXTRA_ARGS="--extra --flags" # Extra arguments for sentry-cli in all build phases
export SENTRY_CLI_RN_XCODE_EXTRA_ARGS="--extra --flags"

export SOURCE_MAP_PATH="path/to/source-maps" # From where collect-modules should read modules
export SENTRY_COLLECT_MODULES="path/to/collect-modules.sh"
export MODULES_PATHS="../node_modules,../my-custom-module"

默认情况下,出于速度原因,禁用调试模拟器构建的源映射上传。如果你想为调试构建生成源映射,可以在上述脚本中将 --allow-fetch 作为参数传递给 SENTRY_CLI_RN_XCODE_EXTRA_ARGS

要将调试符号上传到 Sentry,请使用以下脚本创建一个新的运行脚本构建阶段:

Upload Debug Symbols to Sentry
Copied
/bin/sh ../node_modules/@sentry/react-native/scripts/sentry-xcode-debug-files.sh

要更改默认行为,你可以在 .xcode.env 或构建阶段脚本中传递以下环境变量:

.xcode.env
Copied
export SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable debug symbols upload

export SENTRY_INCLUDE_NATIVE_SOURCES=true # Upload native iOS sources
export SENTRY_CLI_EXECUTABLE="paht/to/@sentry/cli/bin/sentry-cli"
export SENTRY_CLI_EXTRA_ARGS="--extra --flags" # Extra arguments for sentry-cli in all build phases
export SENTRY_CLI_DEBUG_FILES_UPLOAD_EXTRA_ARGS="--extra --flags"

关于在 SENTRY_CLI_DEBUG_FILES_UPLOAD_EXTRA_ARGS 中使用哪些选项的更多信息,请参阅 Sentry CLI Apple Debug Symbols 文档。

如果你使用 nvm 或 Volta,Xcode 可能会找不到默认的 node 二进制文件。此 故障排除示例 中建议的解决方法可以帮助你。

对于 Android,我们通过 Gradle 钩入源映射构建过程。当你运行 npx @sentry/wizard@latest -i reactNative 时,Gradle 文件会自动更新。如果你无法或不想这样做,可以按照以下步骤手动更新文件。

在你的 android 目录中添加一个 sentry.properties 文件。

android/sentry.properties
Copied
defaults.url=https://sentry.io/
defaults.org=example-org
defaults.project=example-project
auth.token=sntrys_YOUR_TOKEN_HERE

我们在 android/app/build.gradle 文件中通过添加以下行来启用 Gradle 集成,添加位置在 android 选项之前:

android/app/build.gradle
Copied
apply from: "../../node_modules/@sentry/react-native/sentry.gradle"

要更改默认行为,你可以传递以下 Sentry Gradle 集成选项和环境变量:

Copied
export SENTRY_PROPERTIES=path/to/sentry.properties
export SENTRY_DISABLE_AUTO_UPLOAD=true # Temporarily disable source maps upload

export SENTRY_DIST=1234
export SENTRY_RELEASE=app@1.0.0

你可以通过在 android/build.gradle 中添加 Sentry Android Gradle 插件 (AGP) 依赖来启用原生符号上传和其他功能。

android/build.gradle
Copied
buildscript {
    dependencies {
        // Other dependencies ...
        classpath("io.sentry:sentry-android-gradle-plugin:5.1.0")
    }
}

你可以在 android/app/build.gradle 中配置插件选项,如下所示:

android/app/build.gradle
Copied
apply plugin: "io.sentry.android.gradle"

sentry {
    // Enables or disables the automatic configuration of Native Symbols
    // for Sentry. This executes sentry-cli automatically so
    // you don't need to do it manually.
    // Default is disabled.
    uploadNativeSymbols = true

    // Enables or disables the automatic upload of the app's native source code to Sentry.
    // This executes sentry-cli with the --include-sources param automatically so
    // you don't need to do it manually.
    // This option has an effect only when [uploadNativeSymbols] is enabled.
    // Default is disabled.
    includeNativeSources = true

    // `@sentry/react-native` ships with compatible `sentry-android`
    // This option would install the latest version that ships with the SDK or SAGP (Sentry Android Gradle Plugin)
    // which might be incompatible with the React Native SDK
    // Enable auto-installation of Sentry components (sentry-android SDK and okhttp, timber and fragment integrations).
    // Default is enabled.
    autoInstallation {
      enabled = false
    }
}