iOS 崩溃收集实战:从「只看到次数、看不到原因」到 Sentry 完整集成

target 'JingNote' do  use_frameworks!  pod 'QCloudRealTime'  # Crash reporting (initialized after privacy consent — see AppDelegate)  pod 'Sentry'end

pod install# → incompatible architecture (系统 Ruby 的 ffi gem 是 x86_64)

arch -x86_64 pod install

// Sentry DSN（来自 Config.plist，客户端公开，非敏感）private(set) var sentryDSN: String = ""// loadConfiguration() 内：sentryDSN = d["SENTRY_DSN"] as? String ?? ""

<key>SENTRY_DSN</key><string>https://xxxxxxxx@xxxxxxx.ingest.sentry.io/xxxxxxx</string>

import Sentryfunc initializeSDKsAfterConsent() {    initializeCrashReporting()   // 最先初始化    initializeSupabaseConfig()    initializeStoreKit()    initializeCloudKit()}/// 初始化 Sentry 崩溃上报。/// 仅在用户同意隐私后调用。/// DSN 缺失或仍为占位符时静默跳过，不影响 App 运行。private func initializeCrashReporting() {    let dsn = ConfigManager.shared.sentryDSN    guard !dsn.isEmpty, dsn.hasPrefix("http") else {        AppLog.debug("[AppDelegate] Sentry 未启用: 未配置有效的 SENTRY_DSN")        return    }    SentrySDK.start { options in        options.dsn = dsn        #if DEBUG        options.environment = "debug"        options.debug = true        #else        options.environment = "production"        options.debug = false        #endif        options.enableCrashHandler = true   // 未捕获异常 / 信号崩溃        options.maxBreadcrumbs = 100        // 崩溃前操作路径        options.tracesSampleRate = 0.0      // 只做 crash，不采性能，省额度    }    AppLog.debug("[AppDelegate] Sentry 崩溃上报已初始化")}

到这里，「采集」就搭好了。但——这还不够。

五、真正的根因：dSYM 上传与符号化

回到最初的痛点：「看不到崩溃原因」。装完 SDK 只解决了崩溃的采集；要在后台看到函数名 + 行号的符号化堆栈，必须把 dSYM（调试符号文件）上传给 Sentry。否则后台看到的还是一堆内存地址，跟你之前的困境一模一样。

有两种方式上传 dSYM：

• • 手动：每次 Archive 后从 .xcarchive/dSYMs/ 把文件拖到 Sentry → Settings → Debug Files。繁琐、易忘。
• • 自动（推荐）：加一个 sentry-cli 的 Run Script build phase，Archive 时自动上传。

下面走自动方案。

5.1 安装 sentry-cli

注意：Sentry 8.x 的 pod 不再自带 sentry-cli（旧版本曾捆绑在 Pods/Sentry/bin/）。需要单独装：

brew install getsentry/tools/sentry-cli# 装在 /opt/homebrew/bin/sentry-cli

5.2 凭据文件 ~/.sentryclirc

把 token / org / project 三个值都放进用户主目录的 ~/.sentryclirc。放主目录、不进 git，既不用在脚本里硬编码密钥，也不用在任何地方暴露：

[auth]token=sntrys_你的OrganizationToken[defaults]org=你的org-slugproject=你的project-slug

同时把凭据文件加进 .gitignore 防误提交：

# Sentry CLI credentials (auth token / org / project) — never commit.sentryclircsentry.properties

5.3 添加 dSYM 上传 build phase

在 Xcode 项目的 app target 里加一个 Run Script build phase（排在所有阶段最后，dSYM 生成后再上传）。对应写进 project.pbxproj 的脚本：

# Sentry dSYM upload - only runs for Release/Archive builds.# Credentials read from ~/.sentryclirc (auth token, org, project).export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"if [ "${CONFIGURATION}" != "Release" ]; then  echo "sentry: skipping dSYM upload for ${CONFIGURATION}"  exit 0fiif ! command -v sentry-cli >/dev/null 2>&1; then  echo "warning: sentry-cli not found in PATH; skipping dSYM upload"  exit 0fisentry-cli debug-files upload --include-sources "${DWARF_DSYM_FOLDER_PATH}" \  || echo "warning: sentry-cli dSYM upload failed"

脚本的几个关键设计：

• • 只在 Release/Archive 跑：Debug 构建直接跳过，不拖慢日常开发（Debug 的 DEBUG_INFORMATION_FORMAT 通常是 dwarf，本就不产 dSYM）。
• • 修正 PATH：Xcode 构建环境默认不含 homebrew 路径，必须显式加上，否则找不到 sentry-cli。
• • 失败降级为 warning：sentry-cli 缺失或上传失败只报 warning，绝不中断构建。换机器/CI 上没配凭据时，打包照常成功。

pbxproj 是文本 plist，手改后务必用 plutil -lint project.pbxproj 校验语法，再用 xcodebuild -list 确认 Xcode 能正常读取。

六、创建 Auth Token（Organization Token）

Sentry 后台有多种 token，dSYM 上传推荐用 Organization Token（不绑定个人账号，scope 自动配好）：

1. 1. Settings → Developer Settings → Organization Tokens → Create New Token
2. 2. 起个名字如 xxx-dsym-upload，创建
3. 3. 立刻复制sntrys_...——token 只显示这一次，关掉页面就再也看不到
4. 4. 粘进 ~/.sentryclirc 的 token=

Organization Token 会自动带上 org:ci scope，这正是 CI 上传 debug file / dSYM 所需的权限，无需手动勾选。

org slug 和 project slug 在哪看

• • org slug：Settings → Organization Settings → Organization Slug，或地址栏 sentry.io/organizations/<org-slug>/
• • project slug：Project Settings → Slug，或地址栏 /projects/<project-slug>/

project slug 可以重命名，且重命名不影响 DSN（DSN 绑 Project ID，不绑 slug）。但重命名后记得同步更新 ~/.sentryclirc 里的 project=——Sentry 后台改名时也会提示「Changing a project's slug can break your build scripts」，原因正是构建脚本引用了 slug。

七、端到端验证

不要只验证「token 能登录」，要验证「token + org + project + 上传」整条链路。

7.1 验证认证与配置读取

sentry-cli info

期望输出：

Default Organization: <org-slug>Default Project: <project-slug>Authentication Info:  Method: Auth Token  Scopes:    - org:ci

看到 org:ci 即 token 有效、scope 正确、org/project 已解析。

排错记录：第一次验证报 401 Invalid token。原因是 ~/.sentryclirc 里 token 那行其实还是占位符（编辑器没保存到目标文件）。排查手法——用脚本只检查 token 行的长度/前缀/有无空格引号，不打印 token 本身，一眼看出「长度 33，前缀 PASTE_...」就是没填进去。

7.2 真实上传一个 dSYM

sentry-cli info 只证明认证通，不证明能上传。做一次真实上传才算端到端验证。手边没有现成 dSYM 时，可以单独编译 Sentry pod 这个 target（Release + 真机架构）产出一个 Sentry.framework.dSYM（它不经过 app 那些会失败的阶段）：

xcodebuild -project Pods/Pods.xcodeproj -target Sentry \  -configuration Release -sdk iphoneos \  -destination 'generic/platform=iOS' \  CODE_SIGNING_ALLOWED=NO DEBUG_INFORMATION_FORMAT=dwarf-with-dsym build

然后真的传上去：

sentry-cli debug-files upload "路径/Sentry.framework.dSYM"

期望输出：

> Found 1 debug information file> Uploaded 1 missing debug information file> File upload complete:  UPLOADED xxxxxxxx (Contents/Resources/DWARF/Sentry; arm64 debug companion)

看到 File upload complete 即整条链路打通。Archive 时的 build phase 执行的是完全相同的 sentry-cli debug-files upload 命令，因此 Archive 必然生效。

八、一个常见疑问：~/.sentryclirc 在 .gitignore 里，Archive 时还生效吗？

生效。 这里有个概念要澄清：

.gitignore 只管「哪些文件不提交到 git 仓库」，与「文件是否存在于磁盘、能否被读取」完全无关。

~/.sentryclirc 物理上就在 /Users/<you>/.sentryclirc，真实存在。gitignore 只是让它不进代码库——这正是我们要的（token 是密钥，绝不能进 git）。

Archive 时的流程：Xcode 执行 build phase → 脚本调 sentry-cli → sentry-cli 运行时从磁盘读 ~/.sentryclirc（通过 $HOME 定位，Xcode 构建阶段的 HOME 就是当前用户主目录）→ 上传。整个过程和 git 无关。

唯一的代价：换机器 / CI

因为它不在仓库里，换电脑或用 CI 打包时那台机器没有这个文件，dSYM 上传会被跳过（但因「失败只 warning」，构建不会失败）。应对：

• • 换机器：新机器上照样建一个 ~/.sentryclirc。
• • CI：把凭据放进环境变量 SENTRY_AUTH_TOKEN / SENTRY_ORG / SENTRY_PROJECT，sentry-cli 会优先读环境变量。

九、最终验证崩溃上报

1. 1. Xcode Product → Archive（Release）。构建日志末尾会出现 [Sentry] Upload dSYMs 阶段，自动上传本次 app 的真实 dSYM。
2. 2. 想立刻测：在某个按钮里临时加一行 SentrySDK.crash()，真机跑 → 触发崩溃 → 重启 App，几十秒后 Sentry 后台 Issues 里就能看到带完整符号化堆栈的崩溃。

从此线上任何崩溃，Sentry 都能给出完整堆栈、设备信息和崩溃前的操作路径——彻底解决「只看到次数、看不到原因」的问题。

十、要点速查

• • 看不到崩溃原因的根因 = dSYM 没上传/没符号化，不是「没装 SDK」。
• • 极简依赖 + 隐私合规项目优先 Sentry（单 SDK、零传递依赖、无 Google 依赖）。
• • DSN 是公开值，可进配置文件；Auth Token 是密钥，只进 ~/.sentryclirc 或环境变量，永不进 git。
• • crash 采集时机跟随现有「同意后初始化」架构，隐私最稳。
• • build phase：Release-only、修正 PATH、失败只 warning。
• • 验证要端到端：sentry-cli info 只证认证，真实 debug-files upload 成功才算通。
• • gitignore ≠ 不生效：文件在磁盘上、运行时被读取，与 git 无关。
• • Apple Silicon 上 pod install 报架构错 → arch -x86_64 pod install。
• • 升级 macOS 后真机/Archive 构建报 rsync Operation not permitted → App target 的 ENABLE_USER_SCRIPT_SANDBOXING 必须为 NO（见附录）。

十一、附录：升级 macOS 后真机构建突然报 rsync「Operation not permitted」

日期：2026-07-08。这是 Sentry 集成落地一段时间后、升级到 macOS 26（Tahoe）踩到的一个构建环境坑，和上面的崩溃收集是同一条链路（嵌入 Sentry.framework），一并记在这里。

11.1 现象：一次真机 Run 冒出十几个红叉

代码没动，真机 Run 直接失败，Xcode 报了 13 个 issue，全部集中在 rsync：

rsync(90339)  unexpected end of file  io_read_nonblocking / io_read_blocking / io_read_flush  rsync_sender  child 90340 exited with status 1rsync(90340)  Sentry.framework/Sentry.bundle/: mkpathat: Operation not permitted  mkstempat: 'Sentry.framework/.Info.plist.xxxxxx': Operation not permitted  Sentry.framework/Info.plist: utimensat (2): No such file or directory  rsync_set_metadata / rsync_downloader / rsync_receiver

看着吓人，其实这十几条是同一个根因的级联：一个 rsync 子进程写文件失败（Operation not permitted），父进程随之读管道失败（unexpected end of file / io_read_*）。关键就一句——rsync 在把 Sentry.framework 拷进 .app 时，写文件/设元数据被系统拒绝。

同时要注意排除误导项：日志里 Sentry 63 issues 全是 @_implementationOnly 的黄色警告，不是错误；ViewController 那条 Value 'self' was defined but never used 也是警告。真正阻断构建的只有 rsync 那组红叉。

11.2 三条看似合理、但这次都没用的路

先说结论：以下三步都是排这类问题的标准动作，值得试，但这次都没解决——记下来是为了让你不要停在这里以为做错了。

1. 1. Product → Clean Build Folder（清 .app 重建）。
2. 2. 删 DerivedData：rm -rf ~/Library/Developer/Xcode/DerivedData/<Proj>-*。
3. 3. 给 Xcode 开「完全磁盘访问权限」（系统设置 → 隐私与安全性）。

三步做完，报错一字不差。说明不是缓存脏、也不是 Xcode 自身的 TCC 权限——问题在更具体的地方。

11.3 系统化定位：先看事实，别猜

① 源完整、目标是半成品。 对比 rsync 的源和目标目录：

# 源：完整.../Build/Products/Debug-iphoneos/Sentry/Sentry.framework  Info.plist        ✅ 存在  Sentry.bundle/    ✅ 存在# 目标：半拷贝的残骸.../SpeechNote.app/Frameworks/Sentry.framework  Info.plist        ❌ No such file or directory  Sentry.bundle/    ❌ 不存在

结论：不是编译出问题，是拷贝拷到一半被打断，留下一个坏 framework，下次构建又基于坏目录继续，反复失败。这也解释了 utimensat ... No such file or directory——rsync 想给还没拷过去的 Info.plist 设时间戳。

② 源没有 quarantine 扩展属性。xattr -lr <源 framework> 输出为空，排除「Gatekeeper 隔离属性导致 rsync 设 xattr 失败」这条常见解释。

③ 系统 rsync 已经不是 GNU rsync 了。

sw_vers          # ProductVersion: 26.5.1  （Tahoe）which rsync      # /usr/bin/rsyncrsync --version  # openrsync: protocol version 29

macOS 用 openrsync 替换了 GNU rsync。openrsync 在保留元数据（权限/时间/扩展属性）时的行为更严格，一旦运行环境受限就直接 Operation not permitted。

④ 谁在跑这个 rsync？ 是 CocoaPods 的嵌入脚本，不是 Xcode 内建拷贝：

# Pods/Target Support Files/Pods-SpeechNote/Pods-SpeechNote-frameworks.shrsync --delete -av ... "${source}" "${destination}"

-a（archive）会保留权限、时间、属主——正是 openrsync 在受限环境下会失败的那些操作。这个脚本对应 Xcode 里的 「[CP] Embed Pods Frameworks」 build phase，而它跑在主 App target 上。

⑤ 决定性证据——脚本沙盒开关。

# 主工程 SpeechNote.xcodeproj：App targetENABLE_USER_SCRIPT_SANDBOXING = YES     # ← 元凶ENABLE_USER_SCRIPT_SANDBOXING = YES# Pods 工程：CocoaPods 自己设的ENABLE_USER_SCRIPT_SANDBOXING = NO      # 正确

11.4 根因

ENABLE_USER_SCRIPT_SANDBOXING = YES 会把 Run Script build phase 关进沙盒，限制它读写的路径。CocoaPods 的嵌入脚本跑在开了沙盒的 App target 上，沙盒里的 rsync 无权往 .app bundle 写文件、设元数据 → 就是那串 mkpathat / mkstempat / utimensat ... Operation not permitted，并留下半个坏 framework。

• • CocoaPods 官方要求这个开关在使用 pod 的 App target 上保持 NO。 Pods 工程本身已经是 NO，坏就坏在主工程被打成了 YES。
• • 为什么以前没事、升级后才炸？这里区分事实与推断：事实是主 target 的开关此刻为 YES、Pods 为 NO；推断是它很可能被 Xcode 的「Update to recommended settings」在某次升级后一键改成了 YES（新版 Xcode 倾向默认开启脚本沙盒）。openrsync 的严格行为让这个本就不该开的开关从「可能容忍」变成「必然失败」。

一句话：根因是 App target 误开了脚本沙盒；Tahoe 的 openrsync 只是把这个隐患从潜伏变成了显式崩溃。

11.5 修复：一个开关，永久生效

Xcode UI 改最稳（构建时 Xcode 开着，直接改磁盘上的 project.pbxproj 可能与之冲突）：

1. 1. 选中蓝色工程 → TARGETS → SpeechNote（不是 PROJECT，也不是 Pods）→ Build Settings。
2. 2. 搜索 User Script Sandboxing → 值从 Yes 改成 No（Debug/Release 一起变）。
3. 3. Product → Clean Build Folder（清掉那个半成品 framework）→ 真机重新 Run。

这个改动落在主工程里，pod install 不会覆盖它（pod install 只重写 Pods 工程和 Target Support Files）。所以改一次永久有效。

11.6 为什么不选别的改法

• • 改 CocoaPods 的 *-frameworks.sh 脚本（比如给 rsync 去掉 -a 的元数据标志）：能绕过，但下次 pod install 会重新生成这个文件、把你的改动冲掉，不可持续。
• • 换 Homebrew 的 GNU rsync：脚本里调的是裸 rsync，构建环境的 PATH 未必能稳定命中 Homebrew 版本，不可靠。
• • 关脚本沙盒：改一个官方推荐值、落在主工程、pod install 不动它——最干净、最持久。

11.7 要点速查

• • rsync Operation not permitted + 一串 io_read_* / mkstempat / utimensat = 拷贝阶段写目标失败，先分清「编译失败」还是「拷贝失败」（看目标 framework 是不是半成品）。
• • Clean、删 DerivedData、给 Xcode 开完全磁盘访问——都试，但这类沙盒问题它们治不了。
• • macOS 新版 /usr/bin/rsync 是 openrsync，对元数据操作更严格，会放大原本被容忍的配置问题。
• • CocoaPods 项目：使用 pod 的 App target 的 ENABLE_USER_SCRIPT_SANDBOXING 必须为 NO；被升级/「Update to recommended settings」改成 YES 是这类构建炸裂的常见诱因。
• • 修构建脚本问题时，优先改主工程里、pod install 不会覆盖的设置，而不是改会被重生成的 Pods 脚本。

2026.07.11 18:沪·青图

📌 声明：本文由 AI 辅助完成