解决 Google Play 上 "App Bundle 包含原生代码，但未上传调试符号" 错误

问题概述

当开发者尝试将 Flutter 应用上传到 Google Play 时，可能会遇到以下警告："此 App Bundle 包含原生代码，但您尚未上传调试符号。我们建议您上传符号文件，以便更轻松地分析和调试崩溃和 ANR 问题"。这是一个常见但容易解决的问题。

问题原因

Google Play 要求包含原生代码（C/C++）的应用提供调试符号文件，以便在应用崩溃或发生 ANR（应用无响应）时能够解析原生堆栈跟踪。Flutter 引擎包含原生代码，因此所有 Flutter 应用都需要处理此要求。

解决方案

以下是几种解决此问题的方法，从最简单的手动方法到完全自动化的解决方案。

方法一：手动创建并上传符号文件（推荐初学者）

这是最直接的方法，适用于大多数 Flutter 项目：

1. 构建应用包：

   flutter build appbundle

2. 找到生成的符号文件目录。路径通常为：

   • build/app/intermediates/merged_native_libs/release/mergeReleaseNativeLibs/out/lib
   • 某些项目可能在 app/build/... 而不是 build/app/...

3. 选择以下架构文件夹（通常包含 3-4 个）：

   • arm64-v8a
   • armeabi-v7a
   • x86_64
   • x86

4. 将这些文件夹压缩为一个 ZIP 文件（名称任意）

macOS 用户注意事项

如果您使用 macOS，需要移除系统自动生成的隐藏文件：

zip -d your_symbols.zip "__MACOSX*"
zip -d your_symbols.zip "*.DS_Store"

5. 在 Google Play Console 中上传：
   • 进入应用发布页面
   • 上传应用包（AAB）后
   • 找到"上传调试符号文件"选项
   • 上传刚才创建的 ZIP 文件

方法二：自动化 Gradle 任务（推荐高级用户）

在 android/app/build.gradle 文件末尾添加以下代码，自动创建符号文件：

tasks.register('zipNativeDebugSymbols', Zip) {
    from 'build/intermediates/merged_native_libs/release/mergeReleaseNativeLibs/out/lib'
    exclude 'armeabi*'  // 排除不再支持的架构
    exclude 'mips'      // 排除不再支持的架构
    archiveFileName = 'native-debug-symbols.zip'
    destinationDirectory = file('build/outputs/bundle/release')
}

tasks.whenTaskAdded { task ->
    if (task.name == 'bundleRelease') {
        task.finalizedBy zipNativeDebugSymbols
    }
}

此配置会在每次执行 bundleRelease 任务后自动创建符号文件，生成的 ZIP 文件将位于 build/outputs/bundle/release/native-debug-symbols.zip。

方法三：Kotlin DSL 配置（适用于 build.gradle.kts）

如果使用 Kotlin DSL 构建脚本，在 android/app/build.gradle.kts 中添加：

tasks.register<Zip>("zipNativeDebugSymbols") {
    from("build/intermediates/merged_native_libs/release/mergeReleaseNativeLibs/out/lib")
    exclude("armeabi*")
    exclude("mips")
    archiveFileName.set("native-debug-symbols.zip")
    destinationDirectory.set(file("release"))
}

afterEvaluate {
    tasks.named("bundleRelease") {
        finalizedBy("zipNativeDebugSymbols")
    }
}

方法四：使用 NDK 调试符号级别配置

如果您希望直接将调试符号包含在应用包中（会增加包大小），可以配置 NDK：

1. 确保已安装 NDK 和 CMake（通过 Android Studio SDK Manager）
2. 在 android/app/build.gradle 中添加：

android {
    defaultConfig {
        ndk {
            debugSymbolLevel 'FULL'  // 或 'SYMBOL_TABLE'（较小）
        }
    }
}

3. 在 local.properties 中指定 NDK 路径：

   ndk.dir=/path/to/ndk

符号级别选择

• SYMBOL_TABLE：提供基本符号信息，文件大小增加较少
• FULL：包含完整调试信息，文件大小显著增加

故障排除

常见错误及解决方案

1. "Could not get unknown property 'android'" 错误

   • 原因：错误的位置添加了配置
   • 解决：确保 ndk 配置在 android.defaultConfig 块内

2. 找不到符号文件目录

   • 原因：项目结构或 Gradle 版本差异
   • 解决：先执行 flutter build appbundle，然后在项目中搜索 merged_native_libs 目录

3. Play Console 拒绝符号文件

   • 原因：包含不支持的架构或无效文件
   • 解决：确保排除 armeabi 和 mips 架构，并移除 macOS 隐藏文件

最佳实践

1. 自动化流程：使用方法二或三的自动化脚本，避免手动操作错误
2. 持续集成：在 CI/CD 流程中包含符号文件生成和上传步骤
3. 版本匹配：确保每次发布的应用包和符号文件版本一致
4. 定期清理：使用 flutter clean 清理旧构建，避免文件路径问题

总结

解决 "未上传调试符号" 警告的主要方法包括手动创建符号文件、自动化 Gradle 任务或配置 NDK 生成调试符号。对于大多数 Flutter 开发者，推荐使用方法二的自动化脚本，它既可靠又高效。

记得每次发布新版本时都要同时上传应用包和对应的调试符号文件，这样才能在应用发生崩溃时获得有意义的错误信息。

更多资源

• Google Play 调试符号官方文档
• Flutter 构建应用包文档