如何使用KSCrash来实现iOS的异常捕获？

KSCrash 是一款开源的 iOS 崩溃捕获库，支持捕获信号异常、Mach 异常、OC/Swift 异常及 ANR（主线程卡顿），还能生成详细的崩溃报告并支持自定义上传逻辑。以下是 KSCrash 的集成、配置与使用全流程：

一、集成 KSCrash

1. 方式一：CocoaPods（推荐）

在Podfile中添加：

ruby
 
pod 'KSCrash'

执行pod install，并打开.xcworkspace文件。

2. 方式二：Swift Package Manager

Xcode 中File > Add Packages，输入仓库 URL：

plaintext

https://github.com/kstenerud/KSCrash.git

选择最新版本并添加到 Target。

3. 方式三：手动集成

从GitHub 仓库下载源码，将KSCrash目录拖入项目，勾选 “Copy items if needed”。

二、核心配置与初始化

KSCrash 需在 App 启动早期（如AppDelegate或main函数）初始化，确保覆盖所有代码执行流程。

1. 基础初始化（Swift）

swift
 

import KSCrash

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // 1. 创建KSCrash配置
    let config = KSCrashConfiguration()
    
    // 2. 配置捕获类型（默认已开启所有类型，可按需调整）
    config.captureExceptions = true        // 捕获OC NSException
    config.captureSignals = true           // 捕获信号（SIGSEGV/SIGABRT等）
    config.captureMachExceptions = true    // 捕获Mach异常
    config.monitorAppHang = true           // 监控ANR（主线程卡顿）
    
    // 3. 初始化KSCrash并启动监控
    KSCrash.sharedInstance().install(with: config)
    
    // 4. 设置崩溃报告回调（可选，用于自定义处理日志）
    KSCrash.sharedInstance().crashReportCallback = { reports in
        guard let reports = reports as? [KSCrashReport] else { return }
        for report in reports {
            // 读取崩溃报告内容（JSON格式）
            if let reportJSON = report.jsonString() {
                print("崩溃报告：\(reportJSON)")
                // 上传报告到服务器（需自定义网络请求）
                uploadCrashReport(reportJSON)
            }
        }
        // 处理完报告后清空缓存
        KSCrash.sharedInstance().purgeReports()
    }
    
    return true
}

// 自定义崩溃报告上传函数
func uploadCrashReport(_ report: String) {
    // 实现网络请求逻辑（如POST到后端接口）
}
 

2. OC 项目初始化示例

objc

#import <KSCrash/KSCrash.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 创建配置
    KSCrashConfiguration* config = [KSCrashConfiguration defaultConfiguration];
    config.captureExceptions = YES;
    config.monitorAppHang = YES;
    
    // 初始化并启动
    [[KSCrash sharedInstance] installWithConfiguration:config];
    
    // 设置回调
    [KSCrash sharedInstance].crashReportCallback = ^NSArray*(NSArray* reports) {
        for (KSCrashReport* report in reports) {
            NSString* json = [report jsonString];
            [self uploadCrashReport:json];
        }
        [[KSCrash sharedInstance] purgeReports];
        return nil;
    };
    
    return YES;
}
 

三、关键功能配置

1. ANR 监控（主线程卡顿捕获）

KSCrash 通过监控 RunLoop 卡顿实现 ANR 捕获，需开启monitorAppHang并配置阈值：

swift

config.monitorAppHang = true
config.appHangThreshold = 5.0 // 卡顿超过5秒触发ANR捕获（默认5秒）
 

2. 自定义用户信息（辅助定位问题）

可在崩溃报告中附加用户 ID、设备信息等：

swift

// 设置用户ID
KSCrash.sharedInstance().userInfo = ["user_id": "123456", "app_version": "1.0.0"]

// 添加自定义日志（崩溃时会包含这些日志）
KSCrash.sharedInstance().log("用户点击了登录按钮")
KSCrash.sharedInstance().log("网络请求失败：timeout")
 

3. 捕获 Swift 错误（自定义异常）

KSCrash 默认不捕获 Swift 的Error，需手动上报：

swift

enum CustomError: Error {
    case dataParseFailed
}

// 业务逻辑中捕获错误并上报
do {
    try parseData()
} catch {
    // 将Swift Error包装为KSCrash异常上报
    KSCrash.sharedInstance().reportUserException(
        name: "DataParseError", 
        reason: error.localizedDescription, 
        language: "Swift", 
        lineOfCode: nil, 
        stackTrace: Thread.callStackSymbols, 
        logAllThreads: true, 
        terminateProgram: false
    )
}
 

四、崩溃报告解析与符号还原

1. 崩溃报告格式

KSCrash 生成的报告为 JSON 格式，包含以下关键信息：

system：设备型号、系统版本、App 版本；
exception：异常类型（如SIGSEGV）、原因、调用栈；
threads：所有线程的堆栈信息；
userInfo：自定义用户信息。

2. 符号还原

崩溃报告中的堆栈地址需通过dSYM文件还原为可读的类名 / 方法名，步骤：

从 Xcode 归档文件中导出dSYM文件（Window > Organizer > 右键归档 > Show in Finder）；

使用 KSCrash 提供的ksymbolicate工具（Python 脚本）还原：

bash
 
运行
 
python ksymbolicate.py -d YourApp.dSYM -o crash_report.json > symbolicated_report.txt

或使用 Xcode 的atos工具手动还原：

bash
 
运行
 
atos -arch arm64 -o YourApp.app/YourApp -l 0x100000000 0x100004abc

五、高级用法：自定义崩溃处理

1. 崩溃前的紧急处理

可通过crashPreprocessor在崩溃时执行紧急操作（如保存数据）：

swift
 
config.crashPreprocessor = {
    // 保存关键数据到沙盒
    saveCriticalData()
    // 禁用某些可能导致死锁的功能
    disableRiskyFeatures()
}

2. 自定义报告存储路径

默认报告保存在Library/Caches/KSCrash，可修改路径：

swift

config.reportPath = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true).first! + "/CrashReports"

六、注意事项

dSYM 文件管理：必须保留与发布版本对应的dSYM文件，否则无法还原符号。建议将dSYM上传到服务器或第三方平台（如 Bugly）。
调试模式：开发阶段可开启KSCrash的调试日志：
swift
```
KSCrash.sharedInstance().logLevel = .debug
```
隐私合规：崩溃报告可能包含设备 ID、用户行为日志等敏感信息，需脱敏后再上传，符合隐私政策要求。
避免递归崩溃：自定义崩溃回调中避免执行复杂逻辑（如大量网络请求），防止触发二次崩溃。

七、KSCrash 核心优势

全类型捕获：覆盖信号、Mach 异常、OC/Swift 异常、ANR；
轻量级：无第三方依赖，体积小，性能损耗低；
高度可定制：支持自定义回调、报告存储、符号还原逻辑；
开源可控：源码透明，可根据需求修改底层逻辑。

posted @ 2025-12-03 16:35 C++大哥来也阅读(2) 评论(0) 收藏举报

刷新页面返回顶部

Ccccaaa