iOS 符号化

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。 虽然可以继续使用 Visual Studio App Center，直到它完全停用，但你可以考虑迁移到几个建议的替代方法。

详细了解支持时间线和替代方法。

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

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

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

未分配的崩溃

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

.dSYM查找捆绑包

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

如果使用 Visual Studio 而不是 Xcode，请参阅 在哪里可以找到用于符号化 iOS 崩溃日志的 dSYM 文件？ 查找 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}'

2. 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}'

3. 使用从第一PATCH步返回的 属性向 symbol_uploads API 发出请求。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

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

App Center 故障报告尚不完全支持对已启用 bitcode 的应用的崩溃进行符号化。 在此期间，建议 禁用 bitcode。 禁用位代码可显著简化符号管理，目前对于 iOS 应用没有任何已知的缺点。

为应用禁用 bitcode

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

通过这些简单的步骤，App Center 故障报告将照常运行。

检索已启用位码的应用的符号

如果要使 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

2. 结果应如下所示：

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

3. 如果返回的 UUID 与调试符号对话框中显示的 UUID 匹配，则双检查：

忽略符号

如果 App Center 没有用于完全符号化崩溃报告的所有符号文件，崩溃将列在“ 取消符号化 ”选项卡中。如果有权访问所需符号，将从此页面上传这些符号。

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