sentry-cocoa-sdk

所有技能 > SDK 设置 > Cocoa SDK

Sentry Cocoa SDK

一款主打简洁实用的向导，可扫描你的 Apple 项目并引导你完成 Sentry 的完整设置。

在以下情况下调用此技能

• 用户要求在 Apple 应用中“添加 Sentry 到 iOS/macOS/tvOS”或“设置 Sentry”
• 用户想在 Swift/ObjC 中使用错误监控、追踪、性能分析、会话回放或日志记录，或在 Swift 中使用指标
• 用户提到 sentry-cocoa、SentrySDK 或 Apple/iOS Sentry SDK
• 用户想监控崩溃、应用卡顿、看门狗终止或性能

**注意：**以下 SDK 版本和 API 以撰写本文时的 Sentry 文档为准（sentry-cocoa 9.15.0）。 实施前请务必对照 docs.sentry.io/platforms/apple/ 进行确认。

---

第 1 阶段：检测

在提出任何建议之前，运行以下命令了解项目：

# Check existing Sentry dependency
grep -rEi "sentry|sentry-cocoa|SentrySPM|SentrySwiftUI" \
  --include="Package.swift" --include="Podfile" --include="Cartfile" \
  --include="Package.resolved" --include="project.pbxproj" . 2>/dev/null | head -20

# Detect UI framework (SwiftUI vs UIKit)
grep -rE "@main|struct .*: App" --include="*.swift" . 2>/dev/null | head -5
grep -rE "AppDelegate|UIApplicationMain|@UIApplicationDelegateAdaptor" --include="*.swift" . 2>/dev/null | head -5

# Detect platform and deployment targets
grep -rE "platforms:|\\.iOS|\\.macOS|\\.tvOS|\\.watchOS|\\.visionOS|IPHONEOS_DEPLOYMENT_TARGET|MACOSX_DEPLOYMENT_TARGET|TVOS_DEPLOYMENT_TARGET|WATCHOS_DEPLOYMENT_TARGET|XROS_DEPLOYMENT_TARGET" \
  --include="Package.swift" --include="project.pbxproj" . 2>/dev/null | head -20
grep -E "platform :ios|platform :osx|platform :tvos|platform :watchos" Podfile 2>/dev/null

# Detect logging
grep -rE "import OSLog|import os\\.log|Logger\\(|CocoaLumberjack|DDLog" --include="*.swift" . 2>/dev/null | head -5

# Detect companion backend
ls ../backend ../server ../api 2>/dev/null
ls ../go.mod ../requirements.txt ../Gemfile ../package.json 2>/dev/null

需要留意的事项：

• Package.swift 或 Podfile 中是否已有 sentry-cocoa？如果有，跳到第 2 阶段（配置功能）。
• 使用 SwiftUI（@main App 结构体）还是 UIKit（AppDelegate）？这决定了初始化模式。
• 使用哪些 Apple 平台？（这会影响可用功能——请参见平台支持矩阵。）
• 是否已有日志库？（可启用结构化日志捕获。）
• SwiftUI 追踪导入项/产品？SentrySwiftUI 仍然存在，但在 SDK 9.4.1+ 中已弃用；对于已发布的二进制产品，建议使用主 Sentry 模块。
• 是否有配套后端？（这会触发第 4 阶段中关于分布式追踪的关联说明。）

---

第 2 阶段：建议

根据你的发现，提出具体建议。不要提出开放式问题，而应先给出方案：

推荐（核心覆盖）：

• 错误监控——始终启用；用于崩溃报告、应用卡顿、看门狗终止、NSError/Swift 错误
• 追踪——应用始终启用；自动检测应用启动、网络、UIViewController、文件 I/O、Core Data
• 性能分析——生产环境中的 iOS/macOS 应用；通过 configureProfiling 进行 UI 性能分析

可选（增强可观测性）：

• 会话回放——面向用户的 iOS 应用；在 iOS 26+ / Liquid Glass 构建中验证遮罩效果
• 日志记录——需要结构化日志捕获时启用
• 指标——需要聚合计数器、仪表或分布数据的 Swift 应用
• 用户反馈——希望收集用户崩溃/错误反馈表单的应用

Cocoa 不支持：

• 定时任务——仅适用于后端
• AI 监控——仅适用于 JS/Python

建议逻辑：

功能	建议启用的情况……
错误监控	始终启用——不可或缺的基线功能
追踪	应用始终启用——开箱即提供丰富的自动检测
性能分析	对性能有要求的生产环境 iOS/macOS 应用（不适用于 tvOS/watchOS/visionOS）
会话回放	面向用户的 iOS 应用；tvOS 可能可用，但不受官方支持
日志记录	已使用 os.log / CocoaLumberjack，或需要结构化日志时
指标	不应产生问题事件的聚合产品或健康信号；仅适用于 Swift，SDK 9.12+
用户反馈	希望通过截图提供应用内错误报告的应用

建议：“我推荐错误监控 + 追踪 + 性能分析。要我也添加会话回放和日志记录吗？”

---

第 3 阶段：引导

安装

选项 1 — Sentry Wizard（推荐）：

需要你亲自运行——该向导会打开浏览器进行登录，并需要 Agent 无法处理的交互式输入。请复制粘贴到终端中：

brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios

它会处理登录、组织/项目选择、身份验证令牌设置、SDK 安装、AppDelegate 更新，以及 dSYM/调试符号上传构建阶段。

完成后，请返回并跳转至验证。

如果用户跳过该向导，则使用选项 2（SPM/CocoaPods），并按下文进行手动设置。

**选项 2 — Swift Package Manager：**文件 → 添加软件包 → 输入：

https://github.com/getsentry/sentry-cocoa.git

或在 Package.swift 中：

.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.15.0"),

SPM 产品——每个目标只能选择一个：

产品	使用场景
Sentry	推荐——静态框架，应用启动速度快；SDK 9.4.1+ 包含 SwiftUI API
Sentry-Dynamic	动态框架替代方案
SentrySwiftUI	用于 SwiftUI API 的旧版/已弃用再导出；仅在维护较旧设置时使用
Sentry-WithoutUIKitOrAppKit	watchOS、应用扩展、命令行工具（Swift < 6.1）
SentrySPM + NoUIFramework 特性	不含 UIKit/AppKit 的源码构建，适用于命令行/无头目标（使用 Xcode UI 需要 SDK 9.7+ / Swift 6.1+ / Xcode 26.4+）

警告：Xcode 允许选择多个产品——只能选择一个。

如果从源码使用 SentrySPM，当前源码构建项目可能会导入 SentrySwift 而非 Sentry；请确认目标中的模块名称。已发布的二进制产品使用 import Sentry。

基于 Swift 6.1+ 特性的退出 UIKit/AppKit 依赖方式（需要 [email protected] 清单）：

// Package.swift (Swift 6.1+)
.package(
    url: "https://github.com/getsentry/sentry-cocoa",
    from: "9.15.0",
    traits: ["NoUIFramework"]
),

// In your target's dependencies:
.product(name: "SentrySPM", package: "sentry-cocoa")

这是 Swift 6.1+ 命令行/无头目标首选的退出依赖方式。它会从源码编译 SDK，因此该特性可以移除 UIKit/AppKit/SwiftUI 链接。对于 Swift < 6.1 的情况，请继续使用 Sentry-WithoutUIKitOrAppKit。

**注意：**从 Xcode 26.4+ 开始，可以在 Xcode UI 中查看软件包特性。在较旧的 Xcode 版本中，只要在 Package.swift 中声明特性，它们仍然有效，但不会显示在图形界面中。

选项 3 — CocoaPods（已弃用；建议使用 SPM）：

platform :ios, '15.0'
use_frameworks!

target 'YourApp' do
  pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '9.15.0'
end

Sentry 计划于 2026 年 6 月底停止发布 CocoaPods 版本；仅对现有 CocoaPods 项目使用此方式。

**已知问题（Xcode 14+）：**出现 Sandbox rsync.samba 错误 → Target Settings → “Enable User Script Sandbox” → NO。

选项 4 — SentryObjC（适用于纯 Objective-C/C++ 项目）：

对于无法启用 Clang 模块（例如 -fmodules=NO）的纯 Objective-C 或 Objective-C++ 项目，请使用 SentryObjC 封装 SDK。它提供与主 SDK 相同的功能，但使用纯 Objective-C 头文件，无需导入 Swift 模块。

SPM：

.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.17.1"),

// In your target's dependencies:
.product(name: "SentryObjC", package: "sentry-cocoa")

或者从发布页面下载 SentryObjC-Dynamic.xcframework.zip。

从常规 Sentry 迁移到 SentryObjC：

• 将 #import <Sentry/Sentry.h> 改为 #import <SentryObjC/SentryObjC.h>
• 将以 Sentry 开头的类型改名为 SentryObjC（例如，SentrySDK → SentryObjCSDK、SentryOptions → SentryObjCOptions）
• 其他 API 均保持一致

大多数用户应使用标准的 Sentry 产品（选项 2）。只有在存在特定需求导致无法使用 Clang 模块时，才使用 SentryObjC。

---

快速入门 — 推荐初始化

完整的 iOS 应用配置，通过合理的默认值启用最常用的功能。在应用启动时，先于任何其他代码添加。

对于 macOS、watchOS、应用扩展或 NoUIFramework 构建，请省略该平台不可用的选项（sessionReplay、截图/视图层级、用户反馈界面、UIKit 跟踪，以及 tvOS/watchOS/visionOS 上的性能分析）。保留适用于检测到的目标且能够编译的核心 dsn、环境、错误监控、跟踪、日志和指标设置。

SwiftUI — 应用入口点：

import SwiftUI
import Sentry

@main
struct MyApp: App {
    init() {
        SentrySDK.start { options in
            options.dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"]
                ?? "https://[email protected]/0"
            options.environment = ProcessInfo.processInfo.environment["SENTRY_ENVIRONMENT"]
                ?? "production"
            // releaseName defaults to "<bundle id>@<version>+<build>"; set only if you need a custom release.

            // Error monitoring (on by default — explicit for clarity)
            options.enableCrashHandler = true
            options.enableAppHangTracking = true
            options.enableReportNonFullyBlockingAppHangs = true
            options.enableWatchdogTerminationTracking = true
            options.attachScreenshot = true
            options.attachViewHierarchy = true
            options.sendDefaultPii = true

            // Tracing
            options.tracesSampleRate = 1.0          // lower to 0.2 in high-traffic production

            // Profiling (SDK 9.0.0+ API)
            options.configureProfiling = {
                $0.sessionSampleRate = 1.0
                $0.lifecycle = .trace
            }

            // Session Replay. Keep production sampling conservative and verify masking on iOS 26+.
            options.sessionReplay.sessionSampleRate = 0.1
            options.sessionReplay.onErrorSampleRate = 1.0

            // Logging (SDK 9.0.0+ top-level; use options.experimental.enableLogs in 8.x)
            options.enableLogs = true

            // Metrics are enabled by default in SDK 9.12+. Set false only to opt out.
            options.enableMetrics = true
        }
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

UIKit — AppDelegate：

import UIKit
import Sentry

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        SentrySDK.start { options in
            options.dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"]
                ?? "https://[email protected]/0"
            options.environment = ProcessInfo.processInfo.environment["SENTRY_ENVIRONMENT"]
                ?? "production"
            // releaseName defaults to "<bundle id>@<version>+<build>"; set only if you need a custom release.

            options.enableCrashHandler = true
            options.enableAppHangTracking = true
            options.enableReportNonFullyBlockingAppHangs = true
            options.enableWatchdogTerminationTracking = true
            options.attachScreenshot = true
            options.attachViewHierarchy = true
            options.sendDefaultPii = true

            options.tracesSampleRate = 1.0

            options.configureProfiling = {
                $0.sessionSampleRate = 1.0
                $0.lifecycle = .trace
            }

            options.sessionReplay.sessionSampleRate = 0.1
            options.sessionReplay.onErrorSampleRate = 1.0

            // Logging (SDK 9.0.0+ top-level; use options.experimental.enableLogs in 8.x)
            options.enableLogs = true

            // Metrics are enabled by default in SDK 9.12+. Set false only to opt out.
            options.enableMetrics = true
        }
        return true
    }
}

警告：SDK 初始化必须在主线程上进行。

---

针对每项已商定的功能

逐项处理功能。为每项加载参考文件，按照其中的步骤操作，并在继续下一项之前进行验证：

功能	参考文件	在以下情况下加载……
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终（基线）
跟踪	${SKILL_ROOT}/references/tracing.md	应用启动、网络、UIViewController 性能
性能分析	${SKILL_ROOT}/references/profiling.md	对性能敏感的生产应用
会话回放	${SKILL_ROOT}/references/session-replay.md	面向用户的 iOS 应用；tvOS 仅在注明限制时使用
日志记录	${SKILL_ROOT}/references/logging.md	需要结构化日志捕获时
指标	${SKILL_ROOT}/references/metrics.md	聚合计数器、量表、分布
用户反馈	${SKILL_ROOT}/references/user-feedback.md	需要应用内错误报告时

针对每项功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按照步骤操作，并验证其正常运行。

---

配置参考

关键 SentryOptions 字段

选项	类型	默认值	用途
dsn	String?	nil	为空时 SDK 会禁用；macOS 可读取 SENTRY_DSN，其他 Apple 平台必须显式设置
environment	String	"production"	例如："production"
releaseName	String?	根据 bundle 推导	默认为 <bundle id>@<version>+<build>
debug	Bool	false	输出详细的 SDK 日志 — 在生产环境中禁用
sendDefaultPii	Bool	false	包含 IP 地址和活跃集成提供的用户信息
enableCrashHandler	Bool	true	崩溃报告总开关
enableAppHangTracking	Bool	true	应用卡顿跟踪总开关
enableReportNonFullyBlockingAppHangs	Bool	true	在受支持的 UI 平台上报告非完全阻塞的卡顿
appHangTimeoutInterval	Double	2.0	判定为卡顿前的秒数
enableWatchdogTerminationTracking	Bool	true	跟踪看门狗终止（iOS、tvOS、Mac Catalyst）
attachScreenshot	Bool	false	出错时截取屏幕截图
attachViewHierarchy	Bool	false	出错时捕获视图层级
tracesSampleRate	NSNumber?	nil	事务采样率（nil = 禁用跟踪）；Swift 会自动装箱 Double 字面量（例如，1.0 → NSNumber）
tracesSampler	Closure	nil	按事务动态采样（优先于采样率）
enableAutoPerformanceTracing	Bool	true	自动插桩总开关
tracePropagationTargets	[Any]	所有请求	接收分布式跟踪标头的字符串或 NSRegularExpression 值
enableCaptureFailedRequests	Bool	true	自动将 HTTP 5xx 错误捕获为事件
enableNetworkBreadcrumbs	Bool	true	为发出的 HTTP 请求添加面包屑
add(inAppInclude:)	Method	bundle 可执行文件	添加视为“应用内”代码的模块前缀
maxBreadcrumbs	Int	100	每个事件的面包屑数量上限
sampleRate	Float	1.0	错误事件采样率
beforeSend	Closure	nil	用于修改或丢弃错误事件的钩子
onLastRunStatusDetermined	Closure	nil	SDK 确定上次启动的崩溃状态后调用
strictTraceContinuation	Bool	false	拒绝来自其他组织的传入跟踪；验证 baggage 标头中的 sentry-org_id（sentry-cocoa ≥9.10.0）
orgId	String?	nil	用于严格跟踪验证的组织 ID；若未显式设置，则从 DSN 主机自动解析（例如，o123.ingest.sentry.io → "123"）
enableLogs	Bool	false	启用结构化日志
enableMetrics	Bool	true	启用 Swift Metrics API（SDK 9.12+）

环境变量

变量	映射到	用途
SENTRY_DSN	dsn	仅作为 macOS 回退值；在 iOS/tvOS/watchOS/visionOS 上显式设置
SENTRY_RELEASE	releaseName	不要假定 Cocoa 会自动提供回退值；如有需要，请显式设置
SENTRY_ENVIRONMENT	environment	不要假定 Cocoa 会自动提供回退值；如有需要，请显式设置

平台功能支持矩阵

功能	iOS	tvOS	macOS	watchOS	visionOS
崩溃报告	是	是	是	否	是
应用卡顿	是	是	是	否	是
看门狗终止	是	是	否	否	是
应用启动跟踪	是	是	否	否	是
UIViewController 跟踪	是	是	否	否	是
SwiftUI 跟踪	是	是	是	否	是
网络跟踪	是	是	是	否	是
性能分析	是	否	是	否	否
会话回放	是	非官方	否	否	否
MetricKit	是（15+）	否	是（12+）	否	否
Metrics API	是	是	是	请确认	是

生产环境设置

降低生产环境中的采样率，以控制数据量和成本：

options.tracesSampleRate = 0.2          // 20% of transactions

options.configureProfiling = {
    $0.sessionSampleRate = 0.1          // 10% of sessions
    $0.lifecycle = .trace
}

options.sessionReplay.sessionSampleRate = 0.1   // 10% continuous
options.sessionReplay.onErrorSampleRate = 1.0   // 100% on error (keep high)

options.enableLogs = true
options.enableMetrics = true             // default true in SDK 9.12+
options.debug = false                   // never in production

---

验证

测试 Sentry 是否正在接收事件：

// Trigger a test error event:
SentrySDK.capture(message: "Sentry Cocoa SDK test")

// Or test crash reporting (without debugger — crashes are intercepted by debugger):
// SentrySDK.crash()  // uncomment, run without debugger, relaunch to see crash report

几秒后检查 Sentry 控制面板。如果没有显示任何内容：

1. 设置 options.debug = true——在 Xcode 控制台中输出 SDK 内部信息
2. 确认 DSN 正确且项目存在
3. 确保在主线程上初始化

---

第 4 阶段：交叉关联

完成 Apple 设置后，检查是否有配套后端尚未接入 Sentry：

# Detect companion backend
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod 2>/dev/null | head -5
cat ../requirements.txt ../Pipfile 2>/dev/null | head -5
cat ../Gemfile 2>/dev/null | head -5
cat ../package.json 2>/dev/null | grep -E '"name"|"dependencies"' | head -5

如果检测到后端，请配置 tracePropagationTargets，以启用端到端分布式追踪，并推荐相应的技能：

检测到的后端	推荐技能	追踪标头支持
Go（go.mod）	sentry-go-sdk	自动
Python（requirements.txt）	sentry-python-sdk	自动
Ruby（Gemfile）	sentry-ruby-sdk	自动
Node.js 后端（package.json）	sentry-node-sdk（或 sentry-express-sdk）	自动

---

故障排除

问题	解决方案
未显示事件	设置 debug: true，确认 DSN 格式正确，并确保在主线程上初始化
未捕获崩溃	在未连接调试器的情况下运行——调试器会拦截信号
未报告应用卡顿	连接调试器时会自动禁用；检查 appHangTimeoutInterval
Session Replay 未录制	确认 sessionSampleRate > 0 或 onErrorSampleRate > 0；在 iOS 26+ 上确认遮罩设置，以及是否有任何手动 Liquid Glass 门控
缺少追踪数据	确认 tracesSampleRate > 0；检查 enableAutoPerformanceTracing = true
缺少性能分析数据	确认在 configureProfiling 中设置了 sessionSampleRate > 0；对于 .trace 生命周期，必须启用追踪
rsync.samba 构建错误（CocoaPods）	Target Settings → "Enable User Script Sandbox" → NO
选择了多个 SPM 产品	只选择一个：Sentry、Sentry-Dynamic、SentrySwiftUI、Sentry-WithoutUIKitOrAppKit 或 SentrySPM（Swift 6.1+ 上需使用 NoUIFramework 特性）
inAppExclude 编译错误	已在 SDK 9.0.0 中移除——改用 options.add(inAppInclude:)
enableAppHangTrackingV2 编译错误	已在 SDK 9.0.0 中移除——改用 enableAppHangTracking；在支持的平台上默认采用 V2 行为
未追踪看门狗终止	需要设置 enableCrashHandler = true（默认已启用）
缺少网络面包屑	需要设置 enableSwizzling = true（默认已启用）
profilesSampleRate 编译错误	已在 SDK 9.0.0 中移除——改用 configureProfiling 闭包