Qt 5.15.2 + Android 开发环境配置指南
本文档记录在 Linux(Ubuntu 22.04)上为Qt 5.15.2搭建 Android 开发环境的完整过程,包含版本兼容性原理、逐步操作、以及实际配置中遇到的全部坑与解决方案。
配套版本:Qt 5.15.2 + Qt Creator 20.0.0 + OpenJDK 11 + Android NDK r21e
目录
- 1. 版本兼容性(核心原理)
- 2. 环境信息速查
- 3. 总体配置流程
- 4. 分步操作
- 5. 关键陷阱与解决方案
- 6. 验证清单
- 7. 故障排查决策树
1. 版本兼容性(核心原理)
Qt 编译 Android APK 时,会用 NDK 的 clang 构建 C++、用 Gradle(AGP)打包,用 sdkmanager 管理 SDK 组件。这些工具对 JDK 版本有相互冲突的要求,版本选错会陷入死结。下表是经过验证的兼容组合:
| 组件 | 推荐版本 | 版本号 | 兼容性说明 |
|---|---|---|---|
| Qt | 5.15.2 | — | 目标 Qt 版本 |
| JDK | OpenJDK 11 | 11.0.31 | Qt 5.15.2 的 AGP 3.x 构建链强制要求 JDK 11;JDK 17 会破坏 Gradle 构建 |
| NDK | r21e | 21.4.7075529 | Qt 5.15.2 官方匹配版本;r24/r25 移除旧 API 导致不兼容 |
| cmdline-tools | ≤ 10.0 | 10.0 | 11.0 及以上强制要求 JDK 17+,与 JDK 11 构建冲突 |
| SDK Platform | android-28 | API 28 | 与 Qt 5.15.2 年代匹配,稳定 |
| Build-tools | 28.0.3 | — | 配合 android-28 |
| Qt Creator | 20.0.0 | — | Android 设置位于Preferences → SDKs → Android |
1.1 为什么 cmdline-tools 必须 ≤ 10.0(版本冲突原理)
这是整个配置中最隐蔽、最耗时的一步,务必理解:
结论:在 Qt Creator 中只能配置一个 JDK。要让这个 JDK(11)同时让 sdkmanager 和 Gradle 构建都满意,cmdline-tools 必须用 10.0 或更早版本。
2. 环境信息速查
本机最终配置的所有路径(后续配置或排错时直接引用):
| 设置项 | 路径 |
|---|---|
| JDK location | /usr/lib/jvm/java-11-openjdk-amd64 |
| Android SDK location | /home/ling/Android/Sdk |
| Android NDK | /home/ling/Android/Sdk/ndk/21.4.7075529 |
| sdkmanager | /home/ling/Android/Sdk/cmdline-tools/latest/bin/sdkmanager |