Sentry React Native 在 Expo 项目中实现 ProGuard 映射文件上传的解决方案

在 React Native 应用开发中，特别是使用 Expo 框架时，开发者经常会遇到 ProGuard 映射文件无法自动上传到 Sentry 的问题。本文将深入探讨这一问题的背景、原因以及解决方案。

问题背景

当我们在 Expo 项目中启用 ProGuard 进行代码混淆时，Sentry 需要这些映射文件来还原混淆后的堆栈跟踪。然而，标准的 Expo 配置并不包含自动上传这些映射文件的功能，导致开发者需要手动处理这一过程。

技术挑战

Expo 的架构设计限制了开发者直接修改 Gradle 文件的能力，而 Sentry 的 Android Gradle 插件（SAGP）正是通过修改这些文件来实现自动上传功能的。这种限制使得标准的 Sentry 集成方案在 Expo 项目中无法直接使用。

解决方案

自定义 Expo 插件

我们可以创建一个自定义的 Expo 插件来绕过这一限制。该插件需要完成以下工作：

1. 修改项目级的 build.gradle 文件，添加 Sentry Android Gradle 插件依赖
2. 修改应用级的 build.gradle 文件，配置 Sentry 插件参数

插件实现要点

const {
  withAppBuildGradle,
  withProjectBuildGradle,
} = require("@expo/config-plugins");

module.exports = function withSentryAndroidGradlePlugin(config, options = {}) {
  // 配置默认参数
  const version = options.version || "4.14.1";
  const uploadNativeSymbols = options.uploadNativeSymbols ?? true;
  const includeNativeSources = options.includeNativeSources ?? true;
  const autoInstallationEnabled = options.autoInstallationEnabled ?? false;
  const autoUploadProguardMapping = options.autoUploadProguardMapping ?? true;

  // 修改项目级 build.gradle
  const withSentryProjectBuildGradle = (config) => {
    return withProjectBuildGradle(config, (projectBuildGradle) => {
      const dependency = `classpath("io.sentry:sentry-android-gradle-plugin:${version}")`;
      
      if (!projectBuildGradle.modResults.contents.includes(dependency)) {
        projectBuildGradle.modResults.contents =
          projectBuildGradle.modResults.contents.replace(
            /dependencies\s*{/,
            `dependencies {\n        ${dependency}`
          );
      }
      return projectBuildGradle;
    });
  };

  // 修改应用级 build.gradle
  const withSentryAppBuildGradle = (config) => {
    return withAppBuildGradle(config, (config) => {
      const sentryPlugin = `apply plugin: "io.sentry.android.gradle"`;
      const sentryConfig = `
  sentry {
      autoUploadProguardMapping = ${autoUploadProguardMapping}
      uploadNativeSymbols = ${uploadNativeSymbols}
      includeNativeSources = ${includeNativeSources}
      autoInstallation {
          enabled = ${autoInstallationEnabled}
      }
  }`;

      let contents = config.modResults.contents;
      if (!contents.includes(sentryPlugin)) {
        contents = `${sentryPlugin}\n${contents}`;
      }
      if (!contents.includes("sentry {")) {
        contents = `${contents}\n${sentryConfig}`;
      }
      config.modResults.contents = contents;
      return config;
    });
  };

  config = withSentryProjectBuildGradle(config);
  config = withSentryAppBuildGradle(config);
  return config;
};

使用方式

在 app.json 中配置插件：

{
  "expo": {
    "plugins": [
      [
        "./withSentryAndroidGradlePlugin",
        {
          "version": "4.14.1",
          "uploadNativeSymbols": true,
          "includeNativeSources": true,
          "autoInstallationEnabled": false,
          "autoUploadProguardMapping": true
        }
      ]
    ]
  }
}

最佳实践

1. 环境区分：在 CI/CD 环境中启用自动上传，在本地开发环境中可以禁用
2. 版本控制：保持 Sentry Android Gradle 插件版本与 Sentry React Native SDK 版本兼容
3. 错误处理：在插件中添加适当的错误处理，确保构建失败时有明确的错误信息

最新进展

Sentry React Native 6.8.0 版本已经将这一功能作为实验性特性引入。开发者现在可以更简单地实现这一功能，而不需要完全自定义插件。

通过上述方案，Expo 项目开发者可以有效地解决 ProGuard 映射文件上传问题，确保 Sentry 能够正确解析混淆后的错误堆栈，提高错误监控的准确性和效率。