Qt 5.15.2 Android环境搭建：JDK/NDK版本匹配全攻略

第一次在 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 r21d（SDK Manager 里对应的版本号是 21.3.6528147，r21e 的 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 差不多 300MB，SDK 装完 10GB 起步，NDK 也要 5GB 左右，建议至少留出 20GB 的剩余空间。第三，也是我最想强调的：安装路径不要出现中文、空格、特殊符号。Qt 装到 D:\Qt，JDK 装到 D:\Java\jdk1.8.0_202，SDK 装到 D:\Android\Sdk，NDK 放在 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 里是否真的包含 JDK：

echo %JAVA_HOME% where java

where java 会列出系统能找到的所有 java.exe 路径，如果列表里有多个，务必第一个是 D:\Java\jdk1.8.0_202\bin\java.exe，否则说明环境变量优先级有问题，后面 Gradle 可能用错 JDK。

3. Android SDK 与 NDK 的正确获取方式

3.1 SDK 怎么装：两条路线都行，新手建议用 Android Studio

Android 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.6528147（r21d）就选它，如果只有更新的版本，选一个 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_ROOT

SDK 和 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-tools；NDK 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 会显示设备类型为 Android，Qt 版本为 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. 从新建项目到编译出第一个 APK

5.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:name="android.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 编译期错误速查：先对照错误类型再动手

以下是我在配置和实际项目里遇到的高频错误，以及对应的处理方式，整理成速查表方便你直接搜错误关键词。

排查时有个通用技巧：点击 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 问题，比如国际化、自定义控件、性能调优，至少不会卡在环境这一关。版本匹配这件事，说到底就是门当户对，别贪新，也别被海量教程带乱节奏。