sentry-ios-swift-setup

Sentry iOS Swift 设置

使用 Swift 和 SwiftUI 在 iOS 项目中安装并配置 Sentry。

何时调用此 Skill

• 用户要求在 Swift 应用中「将 Sentry 添加到 iOS」或「安装 Sentry」
• 用户希望在 iOS 中实现错误监控、链路追踪或会话回放
• 用户提到「sentry-cocoa」或 iOS 崩溃报告

重要： 下方的配置选项和代码示例仅供参考。在实施前请务必对照 docs.sentry.io 进行核实，因为 API 和默认值可能已发生变化。

要求

• iOS 15.0+、macOS 12.0+、tvOS 15.0+、watchOS 8.0+

安装

Swift Package Manager（推荐）

1. File > Add Package Dependencies
2. 输入：https://github.com/getsentry/sentry-cocoa.git
3. 选择版本规则：从 9.5.0 开始的「Up to Next Major」

SPM 产品： 根据你的需求选择：

产品	使用场景
Sentry	默认（静态链接）
Sentry-Dynamic	动态框架
SentrySwiftUI	SwiftUI 视图性能追踪
Sentry-WithoutUIKitOrAppKit	App 扩展或命令行工具

CocoaPods

# Podfile
pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '9.5.0'

然后运行 pod install。

配置

SwiftUI App

import SwiftUI
import Sentry

@main
struct YourApp: App {
    init() {
        SentrySDK.start { options in
            options.dsn = "YOUR_SENTRY_DSN"
            options.debug = true
            
            // Tracing
            options.tracesSampleRate = 1.0
            
            // Profiling
            options.configureProfiling = {
                $0.sessionSampleRate = 1.0
                $0.lifecycle = .trace
            }
            
            // Session Replay
            options.sessionReplay.sessionSampleRate = 1.0
            options.sessionReplay.onErrorSampleRate = 1.0
            
            // Logs (SDK 9.0.0+; for 8.55.0-8.x use options.experimental.enableLogs)
            options.enableLogs = true
            
            // Error context
            options.attachScreenshot = true
            options.attachViewHierarchy = true
        }
    }
    
    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

UIKit App

import UIKit
import Sentry

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        SentrySDK.start { options in
            options.dsn = "YOUR_SENTRY_DSN"
            options.debug = true
            options.tracesSampleRate = 1.0
            options.enableLogs = true
        }
        return true
    }
}

配置选项

选项	描述	默认值
dsn	Sentry DSN	必填
tracesSampleRate	被追踪的 transaction 百分比	0
sessionReplay.sessionSampleRate	被回放的会话百分比	0
sessionReplay.onErrorSampleRate	被回放的发生错误的会话百分比	0
enableLogs	将日志发送到 Sentry	false
attachScreenshot	出错时附加截图	false
attachViewHierarchy	出错时附加视图层级	false

自动插桩功能

功能	捕获内容
App 启动	冷启动/热启动时间
网络	URLSession 请求
UI	UIViewController 加载、用户交互
文件 I/O	读/写操作
Core Data	获取/保存操作
帧	慢帧和冻结帧检测

日志

let logger = SentrySDK.logger

logger.info("User action", attributes: [
    "userId": "123",
    "action": "checkout"
])

// Log levels: trace, debug, info, warn, error, fatal

会话回放

iOS 26+ / Xcode 26+ 注意事项： 由于 Apple 的 Liquid Glass 渲染会破坏遮罩的可靠性，使用 Xcode 26.0+ 构建时，SDK 8.57.0+ 会自动在 iOS 26.0+ 上禁用会话回放。在 iOS < 26 或 Xcode < 26 上，回放仍然有效。要强制启用（请谨慎使用）：options.experimental.enableSessionReplayInUnreliableEnvironment = true。

遮罩

// SwiftUI modifiers
Text("Safe content").sentryReplayUnmask()
Text(user.email).sentryReplayMask()

用户上下文

let user = User()
user.userId = "user_123"
user.email = "[email protected]"
SentrySDK.setUser(user)

// Clear on logout
SentrySDK.setUser(nil)

验证

// Test error capture
SentrySDK.capture(message: "Test from iOS")

// Or trigger a test error
do {
    try someFailingFunction()
} catch {
    SentrySDK.capture(error: error)
}

生产环境设置

SentrySDK.start { options in
    options.dsn = "YOUR_SENTRY_DSN"
    options.debug = false
    options.tracesSampleRate = 0.2  // 20%
    options.sessionReplay.sessionSampleRate = 0.1  // 10%
    options.sessionReplay.onErrorSampleRate = 1.0  // 100% on error
    options.enableLogs = true
}

体积分析（Fastlane）

使用 Fastlane 插件通过 Sentry 跟踪 App 包体积。

安装插件

bundle exec fastlane add_plugin fastlane-plugin-sentry

配置身份验证

# Environment variable (recommended for CI)
export SENTRY_AUTH_TOKEN=your_token_here

或创建 .sentryclirc（添加到 .gitignore）：

[auth]
token=YOUR_SENTRY_AUTH_TOKEN

Fastfile Lane

lane :sentry_size do
  build_app(
    scheme: "YourApp",
    configuration: "Release",
    export_method: "app-store"
  )

  sentry_upload_build(
    org_slug: "your-org",
    project_slug: "your-project",
    build_configuration: "Release"
  )
end

运行体积分析

bundle exec fastlane sentry_size

上传完成后，在 Sentry UI 中查看结果。

疑难解答

问题	解决方案
事件未出现	检查 DSN，启用 debug = true
没有链路追踪	将 tracesSampleRate 设置为 > 0
没有回放	将 sessionSampleRate 设置为 > 0，检查 SDK 8.31.1+。在 iOS 26+/Xcode 26+ 上请参阅上文的 Liquid Glass 注意事项
没有日志	设置 enableLogs = true（SDK 9.0.0+）或 experimental.enableLogs = true（SDK 8.55.0-8.x）
CocoaPods 失败	运行 pod repo update，检查 iOS 15+ target
体积上传失败	检查 SENTRY_AUTH_TOKEN，核实 org/project slug