2. 客户端SDK选型与接入

2.1 主流Crash SDK能力对比

客户端SDK是Crash监控的触角，选择时需要从平台覆盖、符号还原、数据采样率、对应用性能的影响、商业授权等维度评估。以下是当前市场最常用的四款SDK对比：

2.2 集成方式：Gradle / CocoaPods / SPM / 手动

不同SDK分别提供对应的包管理工具集成。以下以Sentry和Bugly为例展示典型集成方式：

2.2.1 Android（Gradle）

// app/build.gradle
plugins {
    id 'com.android.application'
    id 'io.sentry.android.gradle' version '4.8.0' // Sentry Gradle插件
}

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

// 可选：自动上传ProGuard mapping
sentry {
    uploadNativeSymbols = true
    includeProguardMapping = true
}

2.2.2 iOS（CocoaPods）

# Podfile
platform :ios, '13.0'

target 'YourAppTarget' do
  pod 'Sentry', '~> 8.36.0'
  # 符号表上传依赖 sentry-cli，后期脚本执行
end

2.2.3 Bugly Android（自动集成）

// app/build.gradle
android {
    defaultConfig {
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }
}

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

// 符号表上传通过Bugly官方脚本或命令行工具完成

2.3 初始化配置

所有SDK必须尽早初始化（通常在Application.onCreate或didFinishLaunching开头），并传入唯一标识符。以下给出Sentry和Bugly的标准初始化代码：

2.3.1 Sentry Android 初始化

import io.sentry.Sentry;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Sentry.init(options -> {
            options.setDsn("https://examplePublicKey@o0.ingest.sentry.io/0");
            options.setTracesSampleRate(0.2); // 20%性能跟踪采样
            options.setEnableAutoSessionTracking(true);
            // 开发环境关闭错误抽样
            options.setSampleRate(1.0);
        });
    }
}

2.3.2 Sentry iOS 初始化（Objective-C）

#import <Sentry/Sentry.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
        options.dsn = @"https://examplePublicKey@o0.ingest.sentry.io/0";
        options.debug = YES; // 调试阶段开启，发布前关闭
        options.environment = @"production";
        options.enableSwizzling = YES;
    }];
    return YES;
}

2.3.3 Bugly Android 初始化

import com.tencent.bugly.Bugly;
import com.tencent.bugly.BuglyStrategy;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        BuglyStrategy strategy = new BuglyStrategy();
        strategy.setAppChannel("google_play");
        strategy.setAppVersion("2.1.0");
        strategy.setAppReportDelay(10000); // 延迟10秒上报，减少启动竞争

        Bugly.init(this, "your_app_id", false, strategy);
    }
}

2.4 符号表上传：DSYM / ProGuard Mapping / Breakpad Symbols

Crash堆栈地址只有通过符号表才能还原为可读的函数名和行号。不同的SDK和平台对应不同的符号文件格式，上传时机必须是构建产物之后、发布之前。

2.4.1 sentry-cli 上传 dsym（iOS）

# 安装 sentry-cli
brew install getsentry/tools/sentry-cli

# 导出 dsyms
xcrun dsymutil -o App.dSYM.zip App.app.dSYM

# 上传
sentry-cli --auth- YOUR_ \
  upload-dif --org your-org --project your-project \
  --type dsym App.dSYM.zip

2.4.2 Gradle 任务上传 ProGuard mapping（Android）

// 在build.gradle中配置Sentry Gradle插件后，自动生成上传任务
// 手动执行：
./gradlew :app:sentryUploadProguardMappingsRelease

// 验证是否成功：
// 在项目根目录运行
sentry-cli debug-files check -o your-org -p your-project app/build/outputs/mapping/release/mapping.txt

2.4.3 Bugly 符号表上传脚本（Android + iOS）

<pre><code># Android 符号上传（需安装Python + bugly符号上传工具）
python symbol_upload.py \
--app_id YOUR_BUGLY_APP_ID \
--app_key YOUR_BUGLY_APP_KEY \
--version 2.1.0 \
--channel google_play \
--input mapping.txt

# iOS dsym 上传
curl -X POST \
  -F "file=@App.dSYM.zip" \
  -F "app_id=YOUR_BUGLY_APP_ID" \
  -F "app_key=YOUR_BUGLY_APP_KEY" \
  -F "version=2.1.0" \
  https://api.bugly.qq.com/openapi/file/upload/symbol</code>

2.5 整体接入与符号表上传流程

下图展示了从SDK集成到符号文件上传、Crash还原的完整链路：

2.6 性能与稳定性优化要点

• 异步初始化：SDK初始化不应阻塞主线程。Sentry/Bugly均支持后台线程初始化，注意iOS必须在主线程回调safe。
• 采样率动态控制：按用户等级/网络状态动态调整samplesRate，例如仅在WiFi下开启100%采样，移动网络降至10%。
• 符号表缓存：避免每次构建重复上传相同符号表，可使用哈希校验后增量上传，减少CI时间。
• 异常过滤：屏蔽第三方库已知的无害Crash（如系统级NSInternalInconsistencyException），减少数据噪声。
• 上传时机：客户端Crash上报应使用单独的线程池，控制队列大小防止OOM；符号表上传放在后处理阶段，不阻塞发布。

2.7 常见错误与排查