Swift 集成 KSCrash 实现 iOS 应用崩溃日志跟踪与自定义输出

2025-06-10 02:18:01作者：蔡丛锟

在 iOS 应用开发中，崩溃日志的收集和分析对于提升应用稳定性至关重要。KSCrash 作为一款强大的崩溃报告框架，能够帮助开发者捕获各种类型的崩溃信息。本文将详细介绍如何在 Swift 项目中集成 KSCrash，并实现将崩溃日志自定义输出到指定文件的功能。

KSCrash 简介

KSCrash 是一个开源的 iOS/macOS 崩溃报告框架，具有以下特点：

能够捕获多种类型的崩溃，包括 Mach 异常、Unix 信号、C++ 异常等
提供详细的崩溃报告，包括堆栈跟踪、寄存器状态、系统信息等
支持多种安装方式，可根据需求灵活配置
性能开销低，对应用运行影响小

集成步骤

1. 安装 KSCrash

可以通过 CocoaPods 或 Carthage 将 KSCrash 集成到项目中：

# CocoaPods 方式
pod 'KSCrash'

2. 基本配置

在 AppDelegate 中初始化 KSCrash：

import KSCrash

func setupKSCrash() {
    let installation = KSCrashInstallationStandard.sharedInstance()
    installation?.url = URL(string: "http://your-crash-report-server.com")
    
    // 配置崩溃报告
    installation?.install()
    KSCrash.sharedInstance()?.deleteBehaviorAfterSendAll = KSCDeleteNever
    
    // 发送所有待处理的崩溃报告
    installation?.sendAllReports { (reports, completed, error) in
        if completed {
            print("成功发送 \(reports?.count ?? 0) 份崩溃报告")
        } else if let error = error {
            print("发送崩溃报告失败: \(error.localizedDescription)")
        }
    }
}

自定义崩溃日志输出

默认情况下，KSCrash 会将崩溃报告发送到配置的服务器。但在某些场景下，我们可能需要将崩溃日志保存到本地文件，以便后续分析。

1. 创建自定义 Installation

我们可以继承 KSCrashInstallation 类，创建自定义的文件输出 Installation：

class KSCrashInstallationFile: KSCrashInstallation {
    private var reportDirectory: String
    
    init(reportDirectory: String) {
        self.reportDirectory = reportDirectory
        super.init(requiredProperties: nil)
    }
    
    override func sink() -> KSCrashReportFilter! {
        return KSCrashReportFilterPipeline(filters: [
            KSCrashReportFilterJSONEncode(),
            saveToFileFilter()
        ], andDefault: KSCrashReportFilterPassthrough())
    }
    
    private func saveToFileFilter() -> KSCrashReportFilter! {
        return KSCrashReportFilter { (reports, onCompletion) in
            DispatchQueue.global(qos: .background).async {
                // 确保目录存在
                let fileManager = FileManager.default
                if !fileManager.fileExists(atPath: self.reportDirectory) {
                    try? fileManager.createDirectory(atPath: self.reportDirectory, 
                                                   withIntermediateDirectories: true, 
                                                   attributes: nil)
                }
                
                // 保存每个报告到单独的文件
                for (index, report) in reports.enumerated() {
                    if let reportData = report as? Data {
                        let fileName = "crash_report_\(Date().timeIntervalSince1970)_\(index).json"
                        let filePath = (self.reportDirectory as NSString).appendingPathComponent(fileName)
                        try? reportData.write(to: URL(fileURLWithPath: filePath))
                    }
                }
                
                onCompletion?(reports, true, nil)
            }
        }
    }
}

2. 使用自定义 Installation

在应用启动时，使用我们自定义的 Installation：

func setupFileCrashReporting() {
    let documentsPath = NSSearchPathForDirectoriesInDomains(.documentDirectory, 
                                                          .userDomainMask, 
                                                          true).first!
    let crashReportsPath = (documentsPath as NSString).appendingPathComponent("CrashReports")
    
    let installation = KSCrashInstallationFile(reportDirectory: crashReportsPath)
    installation.install()
    
    // 发送所有待处理的崩溃报告
    installation.sendAllReports { (reports, completed, error) in
        // 处理完成回调
    }
}

高级功能扩展

1. 文件名优化

可以为崩溃报告文件生成更有意义的文件名，包含时间戳和进程信息：

private func generateFileName() -> String {
    let formatter = DateFormatter()
    formatter.dateFormat = "yyyyMMdd_HHmmss"
    let timestamp = formatter.string(from: Date())
    
    let processName = ProcessInfo.processInfo.processName
    let processID = ProcessInfo.processInfo.processIdentifier
    
    return "crash_\(processName)_\(processID)_\(timestamp).json"
}

2. 日志压缩

为了节省存储空间，可以在保存前对日志进行压缩：

import zlib

private func compressData(_ data: Data) -> Data? {
    var compressedData = Data()
    let bufferSize = 1024 * 8
    var stream = z_stream()
    
    stream.next_in = (data as NSData).bytes.bindMemory(to: Bytef.self, capacity: data.count)
    stream.avail_in = uInt(data.count)
    
    deflateInit2_(&stream, 
                 Z_DEFAULT_COMPRESSION, 
                 Z_DEFLATED, 
                 MAX_WBITS + 16, 
                 MAX_MEM_LEVEL, 
                 Z_DEFAULT_STRATEGY, 
                 ZLIB_VERSION, 
                 Int32(MemoryLayout<z_stream>.size))
    
    var status: Int32
    repeat {
        var buffer = [UInt8](repeating: 0, count: bufferSize)
        stream.next_out = UnsafeMutablePointer(&buffer)
        stream.avail_out = uInt(bufferSize)
        
        status = deflate(&stream, Z_FINISH)
        
        let count = bufferSize - Int(stream.avail_out)
        if count > 0 {
            compressedData.append(&buffer, count: count)
        }
    } while status == Z_OK
    
    guard status == Z_STREAM_END else { return nil }
    
    deflateEnd(&stream)
    return compressedData
}

3. 日志清理策略

为了避免崩溃日志占用过多存储空间，可以实现自动清理策略：

private func cleanupOldReports() {
    let fileManager = FileManager.default
    guard let files = try? fileManager.contentsOfDirectory(atPath: reportDirectory) else { return }
    
    let now = Date()
    let maxAge: TimeInterval = 7 * 24 * 60 * 60 // 保留7天
    
    for file in files {
        let filePath = (reportDirectory as NSString).appendingPathComponent(file)
        guard let attributes = try? fileManager.attributesOfItem(atPath: filePath),
              let creationDate = attributes[.creationDate] as? Date else { continue }
        
        if now.timeIntervalSince(creationDate) > maxAge {
            try? fileManager.removeItem(atPath: filePath)
        }
    }
}