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文件還原為可讀的類名 / 方法名，步驟：

  1. 從 Xcode 歸檔文件中導出dSYM文件（Window > Organizer > 右鍵歸檔 > Show in Finder）；
  2. 使用 KSCrash 提供的ksymbolicate工具（Python 腳本）還原：

    bash

    運行
python ksymbolicate.py -d YourApp.dSYM -o crash_report.json > symbolicated_report.txt
  1. 或使用 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"

六、注意事項

  1. dSYM 文件管理：必須保留與發佈版本對應的dSYM文件，否則無法還原符號。建議將dSYM上傳到服務器或第三方平台（如 Bugly）。
  2. 調試模式：開發階段可開啓KSCrash的調試日誌：swift
KSCrash.sharedInstance().logLevel = .debug
  1. 隱私合規：崩潰報告可能包含設備 ID、用户行為日誌等敏感信息，需脱敏後再上傳，符合隱私政策要求。
  2. 避免遞歸崩潰：自定義崩潰回調中避免執行復雜邏輯（如大量網絡請求），防止觸發二次崩潰。

七、KSCrash 核心優勢

  • 全類型捕獲：覆蓋信號、Mach 異常、OC/Swift 異常、ANR；
  • 輕量級：無第三方依賴，體積小，性能損耗低；
  • 高度可定製：支持自定義回調、報告存儲、符號還原邏輯；
  • 開源可控：源碼透明，可根據需求修改底層邏輯。