第一次在 Windows 10 上给 Qt 配 Android 环境我大概折腾了一个周末才跑通第一个 APK。不是 Qt 本身多难而是 JDK、SDK、NDK 这三个东西版本牵一发动全身哪个对不上报错都特别迷惑。这篇文章我就以 QT 5.15.2 为例把整套环境配置过程从零撸一遍SDK/NDK/JDK 的版本选择、安装细节、Qt Creator 配置、Gradle 处理、常见报错排查全都会讲到。不管你是刚接触 Qt 的安卓方向还是已经被各种编译错误困住的老哥照着走一遍基本能通。1. 版本选型先读懂 Qt 5.15.2 的脾气1.1 为什么是 JDK 8 NDK r21d 这套组合在动手下载任何东西之前先把版本关系理清楚不然后面全是坑。Qt 5.15.2 是 2020 年底发布的版本它内部的 Android 构建链路当时对接的是 JDK 8、NDK r21、Android API 30 左右的生态。虽然现在最新 JDK 已经到 21、NDK 到 r27但 Qt 5.15.2 不会因为这些工具变新就自动兼容。它内部的 Gradle 模板、编译脚本都是按老版本工具链写的。我用过 JDK 17 编译结果 Gradle 任务直接报 “Unsupported class file major version 61”换成 JDK 8 之后同样的工程一次通过。NDK 更是如此。Qt 5.15.2 的构建脚本依赖 NDK 里的 libgcc、libunwind 这些运行时库而 NDK r23 开始把 libgcc 彻底移除并且调整了整个工具链结构。你如果图新装了 r25链接阶段就是各种 “cannot find -lunwind” 或者 undefined reference这属于 Qt 老版本和 NDK 新版的结构性冲突不是配置能绕过去的。所以老老实实用 NDK r21dSDK Manager 里对应的版本号是 21.3.6528147r21e 的 21.4.7075529 实测也兼容是最稳的。JDK 我推荐装 1.8.0_202这是 JDK 8 比较经典的最后一个公开更新版本。装 JDK 11 理论也可以但实际项目里踩坑概率明显比 JDK 8 高。总结一句话版本不是越新越好这套环境讲究门当户对。1.2 安装前先做好这几件事动手之前有几项准备工作做好后面能省很多事。第一确定系统是 64 位 Windows 10。Qt 的 Android 工具链整体是 64 位的虽然 32 位系统也能跑但 SDK、NDK 各种组件会缺。第二预留磁盘空间JDK 差不多 300MBSDK 装完 10GB 起步NDK 也要 5GB 左右建议至少留出 20GB 的剩余空间。第三也是我最想强调的安装路径不要出现中文、空格、特殊符号。Qt 装到 D:\QtJDK 装到 D:\Java\jdk1.8.0_202SDK 装到 D:\Android\SdkNDK 放在 SDK 的 ndk 目录下这种全英文路径能避开一大堆奇奇怪怪的问题。Windows 上最常见的就是默认装在 C:\Program Files 或 C:\Users\中文用户名 下面然后 Qt Creator 找不到路径、Gradle 解析路径报错非常折腾。还有一个小操作如果电脑上有杀毒软件或者 Windows Defender 的实时防护配置环境的时候建议先临时关一下。之前有人装完 NDK 后马上被杀毒软件隔离了里面的几个可执行文件导致 Qt Creator 一直提示 NDK 无效。等你把环境都装好、第一个 APK 编出来之后再开回来就行。2. JDK 安装与 JAVA_HOME 配置2.1 JDK 8 下载安装的几个细节JDK 从哪下载最简单的是去 Oracle 官网下载 jdk-8u202-windows-x64.exe或者用 Adoptium 的 OpenJDK 8。我个人更推荐 Oracle JDK因为 Qt 的老工具链在 Oracle JDK 上验证最多。下载的时候注意选对 Windows x64 版本别下载成 x86 的。安装时有几个点要留意。安装目录我习惯改成 D:\Java\jdk1.8.0_202改目录不光是为了避开 Program Files 的空格也是为了方便后面配置环境变量时路径短一点、好排查。JDK 8 的安装包会让你选择是否安装公共 JRE建议把 JRE 也装上有些老工具会去 JRE 目录里找东西。整个过程基本上就是一路 Next没有太多的自定义选项安装完先不要急着关命令行我们马上验证。验证 JDK 是否装好不用去写 Java 代码直接在 CMD 里敲两行命令java -version javac -version正常会显示 java version 1.8.0_202 和 javac 1.8.0_202。这里有两个坑一是如果你的机器之前装过其他版本的 JDK命令行输出的可能不是你刚装的这个后面 Gradle 就会很困惑二是如果提示“不是内部或外部命令”那说明 JAVA_HOME 还没配或者 Path 没生效继续看下一节。2.2 JAVA_HOME 与 Path 环境变量配置环境变量配置是很多人第一次卡住的地方其实步骤很简单关键是要理解每一个变量是干嘛的。在 Windows 搜索框输入“环境变量”回车打开“编辑系统环境变量”点击“环境变量”按钮。在“系统变量”区域点击“新建”变量名填 JAVA_HOME变量值填 D:\Java\jdk1.8.0_202注意这里填的是 JDK 的根目录不是 bin 目录。然后在系统变量里找到 Path双击编辑新建一行填 %JAVA_HOME%\bin。保存之后重新打开一个 CMD 窗口再敲 java -version 验证一次。为什么要重新开 CMD因为环境变量修改后已经打开的命令行窗口不会自动刷新很多人在旧窗口里检测发现还是老版本就以为没配成功。同样的道理如果你后面要在 Qt Creator 里编译务必配好环境变量后再启动 Qt Creator不然它读取的也是旧环境。验证完 JAVA_HOME 后还可以顺手验证一下 Path 里是否真的包含 JDKecho %JAVA_HOME% where javawhere java 会列出系统能找到的所有 java.exe 路径如果列表里有多个务必第一个是 D:\Java\jdk1.8.0_202\bin\java.exe否则说明环境变量优先级有问题后面 Gradle 可能用错 JDK。3. Android SDK 与 NDK 的正确获取方式3.1 SDK 怎么装两条路线都行新手建议用 Android StudioAndroid SDK 的安装方式主要有两种我分别说下优缺点。第一种是直接下载 Android Studio安装后用它的 SDK Manager 图形界面勾选组件。这种方式对新手最友好因为 SDK Manager 会把 platform-tools、build-tools、platforms、NDK 的版本列表全部图形化展示想勾哪个就勾哪个还能看到已安装组件的状态。缺点就是 Android Studio 安装包比较大而且你以为装的是 IDE其实我们只是借它的 SDK Manager 来用。第二种是只下载命令行工具 commandline-tools解压后用 sdkmanager 命令装组件。这种方式干净不安装多余的东西但有一个坑新版 commandline-tools 要求 JDK 17 以上而我们的 Qt 编译链路要 JDK 8两者会打架。解决思路很简单下载较早版本的 commandline-tools比如版本号 6200805 左右的发布包这个旧版用 JDK 8 就能跑起来。如果你不想折腾版本兼容就直接走第一条路线装 Android Studio然后用它的 SDK Manager 装组件。我个人的建议是除非你硬盘非常紧张否则就装 Android Studio。它自带的 SDK 目录结构和 Qt Creator 的自动检测兼容性最好我第一遍配环境时用命令行工具Qt Creator 偶尔识别不到某些组件后来用 Android Studio 装的 SDK 就再没出过这个问题。3.2 用 SDK Manager 安装 SDK 与 NDK 的版本细节打开 Android Studio在欢迎界面点击 More Actions SDK Manager或者新建项目后进入 Settings Appearance Behavior System Settings Android SDK。在 SDK Platforms 标签页里勾选 Android 11.0 (API 30)顺便把 Android 10.0 (API 29) 也勾上最低 API 21 以下的平台没必要装。在 SDK Tools 标签页里勾选 Android SDK Build-Tools 30.0.3、Android SDK Platform-Tools、Android Emulator如果你后面要用模拟器、Android SDK Command-line Tools。最关键的一步在 NDK 下拉列表里找到并勾选 NDK version。如果 SDK Manager 列表里能直接看到 21.3.6528147r21d就选它如果只有更新的版本选一个 21 开头的即可。勾选完点 Apply等它下载安装。这个阶段有些组件比较大耐心等就好。安装完成后建议在 SDK 路径下大概看下目录结构应该能看到 platforms、build-tools、platform-tools、ndk 这几个目录。NDK 的路径一般是 D:\Android\Sdk\ndk\21.3.6528147 或者 21.4.7075529 这种带版本号的具体目录。如果这个目录不存在说明 NDK 其实没装成功或者被安全软件拦了。3.3 环境变量ANDROID_SDK_ROOT 和 ANDROID_NDK_ROOTSDK 和 NDK 装好后建议也加两个环境变量这样不仅 Qt Creator 用得上以后你在命令行里跑 adb、sdkmanager 也方便。在系统变量里新建 ANDROID_SDK_ROOT值填 D:\Android\Sdk再新建 ANDROID_NDK_ROOT值填 D:\Android\Sdk\ndk\21.3.6528147按你的实际目录名来。然后在 Path 里追加一行 %ANDROID_SDK_ROOT%\platform-tools。这样 adb 命令在任意命令行位置都能直接调用。这里有个细节老文档经常让配 ANDROID_HOME新版本 SDK 工具更认 ANDROID_SDK_ROOT。最稳妥的做法是两个变量都配上值都指向同一个 SDK 根目录兼容性最好。另外NDK 的路径一定要精确到带版本号的子目录而不是到 ndk 这一层。Qt Creator 识别 NDK 的时候会在你填的目录下找 ndk-build.cmd、toolchains 等文件填到 ndk 这层会直接报错。4. Qt Creator 的 Android 配置与套件检查4.1 在 Qt Creator 里手动指定 JDK/SDK/NDK 路径打开 Qt Creator进入 工具Tools 选项Options 设备Devices Android。这里能看到四个主要配置项JDK location、Android SDK location、Android NDK location、OpenSSL Libraries。JDK location 填 D:\Java\jdk1.8.0_202。Android SDK location 填 D:\Android\Sdk也就是包含着 platforms、platform-tools、ndk 这些子目录的根目录。Android NDK location 填 D:\Android\Sdk\ndk\21.3.6528147注意要精确到带版本号的子目录。OpenSSL Libraries 可以先不填只有你的 Qt 程序里用到了 QSslSocket 或者 HTTPS 请求才需要后面用到再补都不迟。填完之后正常情况下 Qt Creator 会在下方显示绿色的对勾或者至少没有红色错误提示。如果某一行是红色的把鼠标悬停在上面看具体报错。我遇到过的几种红色错误JDK location 报错是因为我填到了 bin 目录SDK location 报错是因为填到了 cmdline-toolsNDK location 报错是因为没精确到版本号子目录。设置完别忘了点 OK 保存然后重新打开这个面板确认一下因为 Qt Creator 偶尔会在更新配置后要求重启 IDE 才加载新识别到的 SDK 组件。4.2 确认 Android 构建套件已经自动生成设置好路径后进入 工具 选项 构建和运行Kits页面。左侧选择“编译器”Compilers正常情况下应该能看到几个 Android 相关的编译器比如 Android Clang (arm64-v8a)、Android Clang (armv7) 等。如果没有说明 Qt 安装的时候没有安装 Android 相关的库这时候需要重新运行 Qt 安装器在组件选择页面勾选 Qt 5.15.2 下的 Android 相关组件比如 Qt 5.15.2 Android、Android x86、Android x86_64 这些把 Android 的库补装完整再回来。左侧再选择“Qt Versions”确认列表里有 Qt 5.15.2 (Android)路径一般指向 D:\Qt\5.15.2\android。然后在“套件”Kits页面里检查一个可用的 Android Kit 会显示设备类型为 AndroidQt 版本为 5.15.2 (Android)编译器和调试器都处于选中状态。如果 Qt Creator 没自动建 Kit你可以手动点击“添加”然后手动选 Android 的 Qt 版本和编译器。名字可以自定义比如 Android arm64-v8a后续新建项目时直接勾这个 Kit 就行。这里有个实际经验如果你电脑上同时装了 MSVC 版本 Qt 和 Android 版本 Qt新建项目时编译器很容易选错。新建项目第一步的 Kit Selection 页面里一定要认准名字中带 Android 的 Kit。选错成 MSVC 或 MinGW Kit编出来的根本不是 APK还会让你误以为自己环境没配好。5. 从新建项目到编译出第一个 APK5.1 新建 Qt Widgets 项目并修改 AndroidManifest配置好环境后先别急着搞复杂项目新建一个空的 Qt Widgets Application 来验证整条链路。项目名称可以叫 AndroidTest创建向导走到 Kit Selection 时只勾选刚才确认过的 Android arm64-v8a 这个 Kit。Qt Creator 会自动生成一个 android 目录里面有 AndroidManifest.xml。这个文件就是 APK 的清单文件类似 Windows 程序的资源文件。打开它重点改两个地方一是包名默认是 org.qtproject.example建议改成你自己的域名倒写例如 com.example.androidtest注意包名里至少有一个点号完全没有点号 Android 会拒绝安装二是版本号versionCode 和 versionName 保持默认也行第一次验证环境不需要纠结。如果你的程序要访问网络比如请求 HTTP 接口需要在 AndroidManifest.xml 里添加权限声明uses-permission android:nameandroid.permission.INTERNET/不声明的话APK 装到手机上是能联网失败而且不会给你任何提示排查起来很隐蔽。在左侧“项目”Projects面板里展开“构建步骤”Build Steps可以看到“Build Android APK”选项里面可以选择自定义 AndroidManifest.xml 路径、APK 打包签名方式。默认情况下Qt 会使用 android-build 目录下的模板自动构建不需要额外改签名Debug 包默认用 debug keystore 签名。5.2 第一次编译Gradle 构建环节怎么处理点击左下角的锤子按钮开始编译。如果你是第一次构建 Android 项目Qt Creator 会在临时目录下生成一个 android-build 的 Gradle 工程目录然后调用里面的 gradlew 脚本执行真正的 APK 构建。这个 Gradle 过程会自动下载 Gradle 发行版、Android Gradle Plugin 以及一堆 Maven 依赖第一次会比较久。这一步是新手最容易被劝退的地方因为 Gradle 的依赖下载源在海外国内网络环境下经常卡住或者中途失败。我当时的做法是等它卡了几次之后手动去 android-build 目录里的 build.gradle 和 gradle/wrapper/gradle-wrapper.properties 文件里做调整。把 build.gradle 里的仓库地址替换成国内镜像把 gradle-wrapper.properties 中的 distributionUrl 替换成可用的镜像地址。实操下来替换仓库之后构建速度会明显提升而且成功率也稳定很多。当然Gradle 第一次构建慢或失败不代表你的环境配置有问题。判断标准是编译日志里如果看到 downloading ... 的字样那多半是网络或镜像问题如果看到 SDK location not found、NDK not configured、Unsupported class file major version 这类字眼那才是环境配置问题回到前面章节去检查。分清这两类问题能省掉很多无效重装。6. 高频报错与避坑实践6.1 编译期错误速查先对照错误类型再动手以下是我在配置和实际项目里遇到的高频错误以及对应的处理方式整理成速查表方便你直接搜错误关键词。报错关键词可能原因解决办法Could not find aapt2SDK Build-Tools 版本不对或缺失在 SDK Manager 里安装 build-tools;30.0.3并检查 build.gradle 中的 buildToolsVersionUnsupported class file major versionJDK 版本过高确认 JAVA_HOME 和 Qt Creator 的 JDK location 都指向 JDK 8Cannot find -lunwind / -lgccNDK 版本过新卸载高版本 NDK安装 NDK r21d 或 r21eNDK not configuredNDK 路径填写错误检查 Android NDK location 是否精确到带版本号的子目录The supplied javaHome seems to be invalidJDK 路径填写错误JDK location 填 JDK 根目录而不是 bin 目录adb: failed to install设备连接问题/存储空间不足执行 adb kill-server 和 adb start-server检查手机存储和调试授权Execution failed for task :acompileDebugJavaWithJavacGradle 缓存或旧构建产物冲突进入 android-build 目录执行 gradlew clean然后重新构建Program type already present依赖库重复引用检查 build.gradle 里的 dependencies移除重复的 jar/aar排查时有个通用技巧点击 Qt Creator 编译输出窗口右侧的“编译输出”符号切到详细日志模式。很多报错看起来只有一行实际完整原因在上面几十行。对着日志里的第一个 ERROR 级别关键词去搜比直接搜最后一行要靠谱得多。6.2 运行期常见问题APK 装上但打不开怎么办编出 APK 只是第一步真正跑起来还会遇到几个非常典型的问题。APK 安装后点击图标没反应这是最常见的情况。先看日志在 Qt Creator 底部“应用程序输出”窗口或者用命令行 adb logcat 查看崩溃日志。常见原因有几种一是 APK 里没有打包 Qt 的 so 库确认构建设置里“Bundle Qt libraries in APK”选项是勾选的二是 targetSdkVersion 和设备的 Android 版本不匹配如果 targetSdkVersion 高于设备系统或者反过来 minSdkVersion 高于设备系统Android 会直接拒绝安装三是动态权限问题Android 6.0 以上涉及定位、读写存储等权限必须在运行时申请Qt 的 QtAndroidExtras 模块提供了 requestPermissions 接口可以调用它申请权限。模拟器上运行特别卡或者闪退多半是模拟器没有开启硬件加速。Windows 10 下用 Android Studio 创建 AVD 时模拟器会默认尝试硬件加速如果你用的是老式第三方模拟器性能差距会非常大。建议直接用物理设备调试USB 连接手机后打开开发者选项里的 USB 调试命令行敲 adb devices 能看到设备串号就说明连接成功。还有一个我踩过的坑Qt Creator 里编出来的 Debug APK 名称默认很长比如 AndroidTest-arm64-v8a-debug.apk放到手机上安装时如果之前装过同包名的旧版本你需要先卸载旧版本再装新的不然会报签名冲突或者库文件残留导致启动异常。这个在新手阶段出现频率很高很多人以为自己的环境坏了其实就是新旧安装包冲突。6.3 三个路径大复盘从头梳理排查顺序如果你已经卡了很长时间不妨把三个路径完全重新走一遍。我一般用这样一个检查顺序能覆盖九成问题。第一步在 CMD 里运行 java -version、echo %JAVA_HOME%、where java确认 JDK 8 是当前优先级最高的 Java 版本。第二步确认 D:\Android\Sdk\platform-tools\adb.exe 存在运行 adb devices 看看是否能识别设备。第三步确认 D:\Android\Sdk\ndk 目录下有两个关键文件ndk-build.cmd 和 source.properties没有的话说明 NDK 损坏或未安装完全。第四步打开 Qt Creator进入 Android 设置页面把三个路径重新手动选择一遍即使看起来已经正确。第五步构建前先执行一次 qmake再编译保证 Qt Creator 读取的是最新环境。这套顺序我前前后后用了很多次基本能定位到是哪个环节出了问题。如果都做完了还是不行那就把 Qt Creator 的构建目录删掉比如项目下的 build-AndroidTest-... 目录重新编译一次。很多时候问题就出在旧构建缓存上和真正的环境配置没关系。最后聊几句我个人的体会。第一次跑通 Android APK 那天我其实没找到什么惊天动地的教程就是不停地看报错、查日志、回退版本最后稳定在 JDK 8 NDK r21 API 30 这套组合上。现在你给我一台干净的 Windows 10按这篇文章的步骤走大概一两个小时就能出 APK。以后再遇到安卓方向的 Qt 问题比如国际化、自定义控件、性能调优至少不会卡在环境这一关。版本匹配这件事说到底就是门当户对别贪新也别被海量教程带乱节奏。