UniApp项目在AGP8+minSdk>21环境下白屏问题解析与解决方案

问题背景

在Android开发中，使用UniApp框架构建应用时，开发者可能会遇到一个特殊的问题：当项目使用Android Gradle Plugin(AGP)8.x版本，并且minSdkVersion设置为大于21时，应用页面会出现白屏现象。而同样的项目，如果使用AGP7.x版本或者将minSdkVersion设置为21或以下，则能正常运行。

问题现象

具体表现为：

1. 使用AGP8.4.1 + minSdk21时，所有UniApp页面显示正常
2. 将minSdkVersion改为24或26后，页面出现白屏
3. 使用AGP7.4.2 + minSdk26时，页面也能正常显示

问题根源分析

这个问题主要源于AGP8.x版本对原生库(so库)打包方式的改变。在AGP8.x中，Google引入了新的原生库打包机制，旨在优化APK大小和应用性能。然而，这种改变与UniApp框架的某些实现机制产生了兼容性问题。

具体来说，当minSdkVersion大于21时，AGP8.x会默认使用新的原生库打包方式，这可能导致：

1. 某些必要的原生库没有被正确包含在最终的APK中
2. 原生库的加载顺序或路径发生了变化
3. 与UniApp的JavaScript引擎交互出现问题

解决方案

针对这个问题，最有效的解决方案是在app模块的build.gradle文件中添加以下配置：

android {
    packaging {
        jniLibs {
            useLegacyPackaging = true
        }
    }
}

这段配置的作用是强制AGP8.x使用传统的原生库打包方式，绕过新机制可能带来的兼容性问题。

深入理解解决方案

useLegacyPackaging = true这个配置项实际上是告诉AGP：

1. 使用旧的.so文件打包方式
2. 保持与AGP7.x及以下版本相同的原生库处理逻辑
3. 确保所有原生库都能被正确包含和加载

这种解决方案虽然简单，但需要注意以下几点：

1. 这只是一个临时解决方案，长期来看应该关注UniApp框架的更新
2. 使用传统打包方式可能会略微增加APK大小
3. 在未来的AGP版本中，这个选项可能会被移除

最佳实践建议

除了上述解决方案外，开发者还应该考虑：

1. 保持UniApp SDK和依赖库的最新版本
2. 定期检查AGP和Gradle的更新日志
3. 在不同minSdkVersion的设备上进行充分测试
4. 考虑使用Android App Bundle(AAB)分发方式，它可以更好地处理不同API级别的原生库

总结

UniApp项目在AGP8.x和minSdk>21环境下出现的白屏问题，本质上是新旧打包机制兼容性问题。通过强制使用传统原生库打包方式可以快速解决问题，但开发者应该持续关注框架和工具的更新，以便在长期维护中获得更好的性能和兼容性。