第2章 Crash捕获组件的初始化配置

2.1 原理解析

崩溃收集SDK（Crash Reporter）是Crash治理体系的数据入口。其核心职责是：在应用发生未捕获异常时，拦截崩溃信号、采集现场上下文（线程堆栈、设备信息、运行状态），并将数据持久化后上报至监控平台。初始化配置的质量直接决定了崩溃数据的完整性、准确性和可分析性。

对于支付SDK场景，初始化配置需覆盖以下三个核心维度：

• SDK接入：选择并集成崩溃收集SDK（如Bugly、Sentry），完成基础初始化。
• 签名信息绑定：将应用身份（AppKey/DSN）与服务端关联，确保崩溃数据归属正确。
• 混淆映射文件上传：将ProGuard/R8生成的 mapping 文件上传至平台，实现堆栈还原。

2.2 崩溃收集SDK接入配置

目前主流方案是 Bugly（腾讯）和 Sentry（开源跨平台）。下表从支付SDK接入的关键维度进行对比：

2.2.1 Bugly 接入（Android）

在 build.gradle 中添加依赖：

dependencies {
    implementation 'com.tencent.bugly:crashreport:3.4.4'
    implementation 'com.tencent.bugly:nativecrashreport:3.9.2'
}

在 Application.onCreate() 中初始化：

public class PayApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // 第三个参数 true 表示开启Debug模式，上线前应改为 false
        Bugly.init(this, "YOUR_BUGLY_APP_ID", BuildConfig.DEBUG);
    }
}

2.2.2 Sentry 接入（Android）

添加依赖和插件：

// build.gradle（项目级）
buildscript {
    dependencies {
        classpath 'io.sentry:sentry-android-gradle-plugin:4.3.0'
    }
}

// build.gradle（模块级）
apply plugin: 'io.sentry.android.gradle'

dependencies {
    implementation 'io.sentry:sentry-android:7.2.0'
}

sentry {
    dsn = "YOUR_SENTRY_DSN"
    autoUploadProguardMapping = true
    uploadNativeSymbols = true
}

初始化配置：

public class PayApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Sentry.init(sentryDsn, options -> {
            options.setEnvironment(BuildConfig.DEBUG ? "development" : "production");
            options.setRelease("pay-sdk@" + BuildConfig.VERSION_NAME);
            options.setEnableAutoSessionTracking(true);
            options.setSessionTrackingIntervalMillis(30000);
        });
    }
}

2.3 签名信息配置与应用身份绑定

签名信息在Crash监控中承担身份校验和数据路由双重作用。对于支付SDK，涉及两个层面的签名：

• 应用签名（APK证书指纹）：用于平台关联应用版本和崩溃数据，在 build.gradle 中配置。
• SDK身份凭证（AppKey / DSN）：在初始化时传入，标识数据归属。

应用签名配置示例：

android {
    signingConfigs {
        release {
            storeFile file("keystore/pay_sdk_keystore.jks")
            storePassword System.getenv("KEYSTORE_PASS") ?: "local_dev_pass"
            keyAlias "pay_sdk_key"
            keyPassword System.getenv("KEY_ALIAS_PASS") ?: "local_dev_pass"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

SDK身份凭证建议通过 AndroidManifest.xml 的 meta-data 或 BuildConfig 字段注入，避免硬编码：

<meta-data
    android:name="BUGLY_APP_ID"
    android:value="YOUR_BUGLY_APP_ID" />

2.4 混淆映射文件上传配置

ProGuard/R8 混淆会重命名类、方法和字段，导致崩溃堆栈无法直接定位源码。映射文件（mapping.txt）记录了原始名与混淆名的对应关系，必须上传至监控平台才能自动还原堆栈。支付SDK通常开启全混淆，映射上传是Crash可分析的前提。

Bugly 自动上传配置

// 在模块级 build.gradle 中
apply plugin: 'bugly'

bugly {
    appId = "YOUR_BUGLY_APP_ID"
    appKey = "YOUR_BUGLY_APP_KEY"
    // 自动上传 mapping 文件
    uploadMapping = true
}

Sentry 自动上传配置

// sentry 配置块已包含映射上传
sentry {
    dsn = "YOUR_SENTRY_DSN"
    autoUploadProguardMapping = true
    uploadNativeSymbols = true
    // 指定 mapping 文件路径（多模块时有用）
    proguardMappingFiles =
        fileTree(dir: "${buildDir}/outputs/mapping", include: "**/mapping.txt")
}

手动上传（备用方案）

当自动上传失败或需要在 CI 管道中独立控制时，可使用命令行工具：

# Bugly 手动上传
curl -X POST \
  -F "appId=YOUR_APP_ID" \
  -F "appKey=YOUR_APP_KEY" \
  -F "file=@app/build/outputs/mapping/release/mapping.txt" \
  https://api.bugly.qq.com/openapi/file/upload/symbol

# Sentry 手动上传
sentry-cli upload-dif \
  --org your-org \
  --project your-project \
  --type proguard \
  app/build/outputs/mapping/release/mapping.txt

2.5 调试与验证

初始化配置完成后，必须通过主动触发 Crash 来验证整条链路是否通畅：

1. 触发测试异常：在支付模块的某个入口（如 PayActivity.onCreate()）临时写入 throw new RuntimeException("Test Crash for SDK init verify");
2. 检查上报：登录 Bugly/Sentry 后台，确认新版本下出现该异常，堆栈信息完整。
3. 验证堆栈还原：对比混淆前后的堆栈，确保 mapping 文件已正确应用，类名、行号可读。
4. 清理测试代码：移除测试异常，发布正式版本。

// 建议在调试工具类中保留条件编译的测试入口
public class CrashTestUtil {
    public static void triggerIfDebug() {
        if (BuildConfig.DEBUG) {
            throw new RuntimeException("【调试用】Crash上报链路验证");
        }
    }
}