在使用 Sentry 监控 Android 应用时，确保崩溃堆栈能够正确**反混淆（Symbolicate）**是至关重要的一步。这依赖于将构建过程中生成的 mapping.txt 文件正确上传到 Sentry 服务器。
虽然 Sentry Gradle 插件通常能自动完成这一步骤，但当自动上传失败或被禁用时，许多开发者会转向手动上传。本文将深入解析 Sentry 符号化背后的核心原理，并提供一个保证成功的手动上传指南。
核心原理：Sentry 如何关联崩溃和 Mapping 文件？
Sentry 关联混淆堆栈和 mapping.txt 文件并不是简单地依靠版本号（Release Name），而是依赖于一个唯一的“钥匙”：Debug Identifier (Debug ID) ，或称为 UUID。
Sentry 的符号化流程包含两个相互独立的步骤：
-
APK/AAB 注入（钥匙的生成与携带）
在构建过程中，Sentry Gradle 插件会生成一个唯一的 UUID，并将它注入到您的应用包（APK/AAB）中的一个属性文件（通常是 sentry-debug-meta.properties）。当应用崩溃时，Sentry SDK 会读取这个 UUID，并将其随崩溃事件一同发送给 Sentry 服务器。
- 对应的配置项：
includeProguardMapping.set(true)
- 对应的配置项：
-
Mapping 文件上传（钥匙的匹配与存储）
您将 mapping.txt 文件上传到 Sentry 服务器。上传的文件中也必须携带相同的 UUID 和 Release 版本号。Sentry 服务器存储这些文件，等待接收带有匹配 UUID 的崩溃事件。
关键结论： 如果您的 APK 中没有注入 UUID（即 includeProguardMapping 为 false），那么 Sentry 服务器收到的事件就没有“钥匙”，即使您手动上传了 mapping.txt 文件，服务器也无法找到精确匹配，导致解析失败。
手动上传 ProGuard Mapping 文件的正确流程
当 autoUploadProguardMapping 设置为 false 或自动上传失败时，您可以放心地使用 Sentry CLI 手动上传。前提是您的构建配置中 includeProguardMapping 必须为 true。
步骤 1: 准备 Sentry CLI 环境
您需要安装 Sentry CLI 并配置认证信息。对于自建 Sentry 服务器，必须指定 URL。
Bash
# 1. 确保安装了 Sentry CLI (如果未安装)
npm install -g @sentry/cli
# 或使用下载的二进制文件，例如 sentry-cli-Windows-x86_64.exe
配置环境变量（推荐方式）
在您的命令行或 CI/CD 脚本中设置以下四个关键环境变量：
Bash
# 替换为您的自建 Sentry 服务器地址
export SENTRY_URL="https://sentry.mycompany.com"
# 替换为您的认证令牌
export SENTRY_AUTH_TOKEN="YOUR_AUTH_TOKEN"
# 替换为您的组织 slug
export SENTRY_ORG="your-org-slug"
# 替换为您的项目 slug
export SENTRY_PROJECT="your-project-slug"
步骤 2: 确定 Release 版本号
手动上传时，您必须提供正确的 Release 版本号 (--version)，以便 Sentry 能够将 mapping.txt 与您的应用版本关联起来。
查看方法：
- 检查您 Android 代码中 Sentry SDK 初始化时的
options.release值。 - 或查看 Sentry 平台上该应用已记录的崩溃事件中显示的 Release 值。
步骤 3: 使用 debug-files upload 命令上传
请避免使用旧版且已弃用的 upload-proguard 命令。请使用更通用、更健壮的 debug-files upload 命令，并确保包含 --version 参数。
Bash
# 替换为您的 mapping 文件路径和应用版本号
MAPPING_FILE_PATH="/path/to/your/android/mapping.txt"
APP_RELEASE_VERSION="com.example.app@1.0.0+10"
sentry-cli debug-files upload \
--type proguard \
--version "${APP_RELEASE_VERSION}" \
--include-sources \
--wait \
"${MAPPING_FILE_PATH}"
| 参数 | 作用 |
|---|---|
--type proguard | 指定上传的文件类型是 ProGuard Mapping。 |
--version | 核心。关联到您的应用版本，必须与 SDK 配置完全一致。 |
--include-sources | 允许 Sentry 显示源代码上下文（如果可用）。 |
--wait | 等待 Sentry 服务器确认上传和处理完成。 |
步骤 4: 验证上传结果
登录您的 Sentry 平台，进入 项目设置 (Project Settings) > Debug Files (调试文件) 页面。您应该能看到新上传的 mapping.txt 文件，并正确关联到您指定的 Release 版本。
避坑指南：关于 upload-proguard 的告诫
您可能会发现旧的 upload-proguard 命令依然存在。虽然它可以上传文件，但它已弃用，并且在最新的 Sentry 架构中可能无法像 debug-files upload 那样稳定地处理 UUID 和 Debug ID 的关联。
如果您的自建 Sentry 版本较旧，导致新的 debug-files upload 报告 404 resource not found 错误，这意味着您的服务器不支持新的 API 路由。在这种极端情况下，您只能：
- 升级 Sentry 服务器（最彻底的解决办法）。
- 临时使用
upload-proguard，但必须包含--version参数来尝试关联 Release：
Bash
# 不推荐使用，仅作为旧版服务器的应急方案
sentry-cli upload-proguard \
--version "YOUR_APP_RELEASE_VERSION" \
"xxx.mapping"
通过理解 Sentry 依赖 UUID 注入 (由 includeProguardMapping=true 完成) 和 正确上传 (使用 CLI 并指定 --version) 这两个步骤，您将能够彻底解决 Android 崩溃堆栈的符号化问题。
