如何为Android项目向Sentry上传源上下文关联源码堆栈

前提：已完成ProGuard符号解析配置，堆栈能正常还原混淆类名/方法名的基础上，按以下步骤配置即可生效。

优先用Gradle插件自动上传（零坑方案，不用手动敲cli命令） #

• 先确认版本基线：Sentry Android Gradle插件版本≥3.1.0，低于这个版本的插件本身不支持源码上下文自动上传，先升版本再操作。
• 在模块级build.gradle（或build.gradle.kts）的sentry配置块补全以下参数：

sentry {
    // 原有ProGuard相关配置保持不动
    includeProguardMapping = true
    autoUploadProguardMapping = true
    // 新增以下源码关联核心配置
    includeSources = true
    uploadSourceContext = true
    // 三个参数必须和Sentry后台信息完全匹配，auth token需要开project:write权限
    org = "你的Sentry组织标识"
    projectName = "你的Sentry项目名"
    authToken = "你的Sentry账号Auth Token"
}

• 配置完成后正常执行release渠道打包命令即可，插件会自动匹配当前构建的build id，同步上传mapping、native符号、对应源码上下文，不需要额外手动操作。

手动sentry-cli上传的正确操作（补全你之前命令缺失的参数） #

你之前的两个cli操作都漏了关键参数，才会导致上传后不生效，按下面步骤走：

1. 先确认当前测试APK的build id，执行sentry-cli difutil check 你的APK文件路径，记录返回的build id，后续上传的所有文件必须和这个id匹配。
2. 上传基础调试符号，带源码关联参数：

sentry-cli upload-dif \
  --org "你的Sentry组织标识" \
  --project "你的Sentry项目名" \
  --auth-token "你的Auth Token" \
  --platform android \
  --include-sources \
  app/build/intermediates/merged_native_libs/release/out/lib \
  app/build/outputs/mapping/release/mapping.txt

3. 手动生成并上传源码bundle：

# 打包源码时必须把主源码目录、编译生成代码目录都包含进去，否则ViewBinding、DataBinding、路由生成类的代码关联不上
sentry-cli difutil bundle-sources \
  app/src/main/java \
  app/src/main/kotlin \
  app/build/generated/source

# 上传源码bundle必须指定--type sourcebundle，否则Sentry会把它当成普通符号文件处理，不会用于源码关联
sentry-cli upload-dif \
  --org "你的Sentry组织标识" \
  --project "你的Sentry项目名" \
  --auth-token "你的Auth Token" \
  --type sourcebundle \
  ./*.src.zip

常见不生效排查点 #

• 构建id不匹配：测试崩溃的APK必须和你上传符号、源码包时的构建产物完全一致，哪怕改一行代码重新打包，build id就会变，之前传的文件全部失效。
• 权限问题：Auth Token必须勾选project:write、project:releases权限，只读权限的token上传文件会在后台静默失败，表面看传完了实际没生效。
• 行号错位：如果项目接了字节码插桩类SDK（埋点、隐私合规、热修复等），要把Sentry插件的执行顺序放到插桩插件之后，否则插桩修改后的代码行号和原始源码对不上，会出现源码显示错位的问题。
• 后台延迟：文件上传完成后等3-5分钟再触发崩溃测试，Sentry后台处理符号、源码包有一定延迟，刚传完立刻测大概率关联不上。

内容的提问来源于stack exchange，提问作者Jort de Bokx