iOS 符号

重要

Visual Studio App Center 于 2025 年 3 月 31 日停用,但分析和诊断功能除外,这些功能将继续受支持,直到 2026 年 6 月 30 日。 了解详细信息

macOS、tvOS 和 iOS 崩溃报告显示发生崩溃时应用的所有正在运行线程的堆栈跟踪。 堆栈跟踪仅包含内存地址;不是了解崩溃所需的类名、方法、文件名或行号。

若要获取转换的内存地址,需要将 dSYM 包上传到 App Center,其中包含符号化所需的所有信息。 可以从 Apple 的官方开发人员文档了解有关符号的详细信息。

App Center 生成和分发服务可以自动生成有效的 dSYM 和源映射 .zip 文件,并将该文件上传到诊断服务。 如果使用 App Center 生成并自动将应用分发给最终用户,则无需手动获取和上传符号文件。

未符号化的崩溃

未符号化的崩溃会显示在 App Center 诊断部分中,这样一来,即使在上传符号之前,也可以查看一些详细信息。 这些崩溃中缺少的符号将显示在“未符号化”选项卡中。如果上传缺少的符号,则未符号化崩溃组将被符号化崩溃组替换。

.dSYM查找捆绑包

  1. 在 Xcode 中,打开 “窗口 ”菜单,然后选择 “组织者”。
  2. 选择“ 存档 ”选项卡。
  3. 在左侧栏中选择你的应用。
  4. 右键单击最新的存档,然后选择“ 在查找器中显示”。
  5. 右键单击 .xcarchive Finder 中的文件,然后选择“ 显示包内容”。
  6. 应会看到一个名为 dSYMs 包含 dSYM 捆绑包的文件夹。
  7. 创建 dSYM 捆绑包的 zip 文件。

如果使用 Visual Studio 而不是 Xcode,请参阅 在哪里可以找到 dSYM 文件来符号化 iOS 故障日志? 以查找 dSYM 文件。

上传符号

App Center 门户

  1. 登录到 App Center 并选择你的应用。
  2. 在左侧菜单中,导航到“ 诊断 ”部分并选择“ 符号”。
  3. 在右上角,单击“ 上传”符号 并上传文件。
  4. App Center 为符号编制索引后,崩溃日志将被符号化处理。

React Native iOS 应用

若要获取 React Native iOS 文件的符号文件,请在 Mac 上使用 dSYM 包和应用的 JavaScript 源映射创建 ZIP 文件。 源映射应命名 index.ios.map。 以下命令将生成发布版本的源映射:

react-native bundle --entry-file index.ios.js --platform ios --dev false --reset-cache --bundle-output unused.jsbundle --sourcemap-output index.ios.map

App Center API

通过 API 上传符号的过程涉及一系列三个 API 调用:一个用于在后端分配空间,一个用于上传文件,另一个用于更新上传状态。 第一个 API 调用的正文应设置为 symbol_typeApple

  1. POST触发对symbol_uploads API 的请求。 此调用为您的文件在后端分配空间,并分别返回一个symbol_upload_id属性和一个upload_url属性。
curl -X POST 'https://api.appcenter.ms/v0.1/apps/{owner_name}/{app_name}/symbol_uploads' \
    -H 'accept: application/json' \
    -H 'X-API-Token: {API TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{JSON BODY}'
  1. 使用从第一步返回的upload_url属性,添加PUT标头,并提供您磁盘上文件的位置,发出"x-ms-blob-type: BlockBlob"请求。 此调用会将文件上传到后端存储帐户。 详细了解 PUT Blob 请求标头
curl -X PUT '{upload_url}' \
    -H 'x-ms-blob-type: BlockBlob' \
    --upload-file '{path to file}'
  1. 使用PATCH第一步返回的属性向symbol_upload_id发出请求。 在请求正文中,指定是要将上传 committed 状态设置为(已成功完成)上传过程,还是 aborted (未成功完成)。
curl -X PATCH 'https://api.appcenter.ms/v0.1/apps/{owner_name}/{app_name}/symbol_uploads/{symbol_upload_id}' \
    -H 'accept: application/json' \
    -H 'X-API-Token: {API TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{ "status": "committed" }'

注释

符号上传 API 不适用于大于 256MB 的文件。 使用 App Center CLI 上传这些文件。 可以按照 App Center CLI 存储库中的说明安装 App Center CLI

App Center 命令行界面 (CLI)

还可以使用 CLI 上传符号文件:

appcenter crashes upload-symbols --symbol {symbol file}

Bitcode

Apple 引入了 Bitcode,允许发送到 App Store 的应用由 Apple 本身重新编译并应用最新优化。 如果启用了 Bitcode,则为应用商店中应用生成的符号将不同于你自己的生成系统生成的符号。

App Center 崩溃报告尚不完全支持对已启用 bitcode 的应用程序崩溃进行符号化处理。 同时,我们建议你 禁用 bitcode。 禁用位代码可显著简化符号管理,目前 iOS 应用没有任何已知的缺点。

为应用禁用 bitcode

  1. 在 Xcode 中,通过单击项目导航器中的顶级元素打开项目设置
  2. 转到“生成设置”页
  3. 搜索 bitcode
  4. 在结果中,将值从“是”更改为 “否”
  5. 重新构建你的应用

通过这些简单的步骤,App Center 崩溃报告将像往常一样运行。

检索启用了 bitcode 的应用程序的符号

如果要保持 bitcode 启用状态,可以按照以下步骤下载正确的 dSYM 文件:

  1. 打开 Xcode 的管理器
  2. 选择已上传到 iTunes Connect 的应用的特定存档
  3. 单击“下载 dSYM”按钮。 此步骤会将已编译的 Bitcode dSYM 文件插入到原始存档中。
  4. 将符号上传到 App Center 中的相应应用和版本

如果 Xcode 组织者不提供任何新符号,则必须按照以下步骤从 iTunes Connect 门户下载 dSYM 文件:

  1. 在 iTunes Connect 门户中选择你的应用
  2. 选择顶部的“活动”选项卡
  3. 选择包含缺失符号的应用的内部版本
  4. 单击“下载 dSYM”链接
  5. 将下载的文件上传到 App Center。 此文件包含 App Center 对崩溃进行符号化所需的符号。

符号问题疑难解答

如果在上传符号并禁用位代码后,您的崩溃仍然未符号化,可能是因为上传的 dSYM 文件与 App Center 所需的文件不匹配。 上传 dSYM 文件时,App Center 会根据其 UUID 将其匹配到正确的应用版本。

可以使用名为 dwarfdump 的 CLI 工具仔细检查 dSYM 文件是否具有正确的 UUID。

  1. 在 dSYM 文件中查找 UUID:
dwarfdump --u CrashProbeiOS.app.dSYM
  1. 结果应如下所示:
UUID:ADF53C85-4638-3EFF-A33C-42C13A18E915 (armv7)CrashProbeiOS.app.dSYM/Contents/Resources/DWARF/CrashProbeiOS
UUID:D449E33D-7E74-379D-8B79-15EE104ED1DF (arm64)CrashProbeiOS.app.dSYM/Contents/Resources/DWARF/CrashProbeiOS
  1. 仔细检查返回的 UUID 是否与调试符号对话框中显示的 UUID 匹配:

App Center 显示所需符号的 UUID

忽略符号

当 App Center 缺少完全符号化崩溃报告的所有符号文件时,崩溃将被列在 “未符号化” 选项卡中。如果您有权访问所需的符号文件,请从此页面上传它们。

如果无法上传符号,可以通过选择表中的行并单击“忽略版本”按钮将其标记为“忽略”。 此按钮告知 App Center 处理崩溃,并使用文件中的符号尽可能全面地对其进行符号化。 完成处理后,它们将显示在“ 崩溃 ”选项卡中部分符号化。 新的崩溃,也依赖于标记为被忽略的相同符号 ID 将绕过 未配置 选项卡,因为它们传入并流经系统。