我第一次搭Qt 5.12.12的安卓开发环境时心态是彻底崩的。明明每一步都照着教程点Qt Creator里就是反复报各种SDK相关错误一会是build-tools找不到一会是NDK不兼容换一个版本又冒出新的问题。折腾了两天才摸清规律——这套组合的坑九成出在“版本”这两个字上。这篇文章写给要在Windows上用Qt 5.12.12开发安卓App的人。不是那种讲原理讲得云里雾里的文章而是把我踩过坑之后沉淀下来的完整流程直接给你包括JDK、SDK Platform、Build-Tools、NDK的精确版本组合Qt Creator里每一处需要手动填的路径以及编译、签名、真机安装的完整链路。文末还整理了一份高频报错排查清单基本上你遇到的报错都能在里面找到对应解法。1. 版本不是越新越好先把四件套的兼容关系理清1.1 Qt 5.12.12为什么还在被大量使用Qt 5.12是LTS长期支持系列5.12.12是这个系列的最终补丁版本等于说它把整个5.12分支的bug修到了最干净的状态。很多商业项目和上架App至今仍锁在这个版本原因无非两点稳定性足够社区资料足够多。出了问题搜索引擎一捞一大把不像Qt 6的某些冷门模块遇到问题连提问都问不明白。但问题恰恰出在这里——很多人装Qt 5.12.12时顺手就把“最新版思维”带进来了Android SDK装最新的、NDK装最新的、JDK装最新的结果就是编译链全线崩溃。5.12.12是2021年发布的它对应的工具链版本停留在那个年代。你让一个2021年的工具链去调2024年的SDK它自然不认识。1.2 四件套的版本锁定逻辑安卓开发环境搭建涉及四个核心组件每个都有严格的版本边界JDK必须是8。Qt 5.12.12内置的Android Gradle插件只认JDK 8装JDK 11或17会直接报“The Android Gradle plugin requires JDK 8”。SDK Platform装android-28最稳。严格来说5.12.12最高能支持到API 29但根据大量实测反馈用28的翻车概率最低。Build-Tools装28.0.3。这个要和SDK Platform配套装34.0.0这种最新版反而会让aapt2崩溃。NDKr21d版本号21.4.7075429。r20b也能用但r22以上会直接编译报错因为NDK内部编译器结构变了Qt 5.12.12的构建脚本跟不上。这套组合不是拍脑袋定的是很多人在5.12.12上反复试出来的“甜点版本”。我的建议是你先把这套组合完整跑通再考虑升级其中某个组件。不然报错时你会分不清是配置问题还是版本冲突。1.3 版本冲突时典型的报错特征版本不匹配的报错有个特点信息很具迷惑性。比如“Calling bash --version failed”这种看起来是环境问题实际是NDK路径不对或NDK版本过新。再比如“The SDK Build Tools revision (34.0.0) is too low”实际上不是太低而是工具链兼容性检查逻辑被绕晕了。所以你记住一句话在这套环境里凡是莫名其妙的报错优先怀疑版本而不是怀疑自己操作失误。这是我对所有被SDK坑到怀疑人生的朋友说的第一句话。2. 下载与安装锁定 JDK 8 SDK 28 NDK r21d2.1 JDK 8的选择与安装细节JDK 8的获取方式有讲究。Oracle官方JDK 8u202是最后一个免费商用版本之后的8u211虽然是免费但引入了Oracle Technology Network许可协议团队商用有一定风险。个人开发无所谓但如果是公司项目我更推荐用Adoptium Temurin 8也就是Eclipse Adoptium项目提供的OpenJDK 8构建版或者Azul Zulu 8。它们版本更新安全补丁新而且没有任何许可坑。安装JDK后建议直接设置JAVA_HOME环境变量变量名JAVA_HOME 变量值C:\Program Files\Eclipse Adoptium\jdk-8.0.392.8-hotspot然后在Path里追加%JAVA_HOME%\bin。设置完打开cmd输入java -version确认输出是1.8.0_xxx开头而不是11或17。注意JDK 8的安装路径里尽量不要有空格和中文。虽然大部分情况下带空格的路径也能工作但Qt的构建脚本偶尔会在处理路径时抽风保险起见放在C:\Java\jdk1.8.0_392这种短路径下最省心。2.2 Android SDK不走Android Studio用命令行工具最干净很多人一听装Android SDK下意识就去装Android Studio。其实如果你只是为了Qt开发安卓App完全没必要装这个两三个G的IDE。用Google官方的“command-line tools”就够了轻量、可控、不绑定任何IDE。先到Android开发者官网下载“Command line tools only”版本。解压后记住目录结构必须是这样D:\Android\Sdk └── cmdline-tools └── latest ├── bin ├── lib └── ...即解压出来的文件夹比如cmdline-tools-windows-11076708_latest要改名成latest放进D:\Android\Sdk\cmdline-tools\目录下。如果你直接放成D:\Android\Sdk\cmdline-tools\cmdline-tools-windows-11076708_latest\bin这种结构后面运行sdkmanager会提示找不到SDK。SDK目录建好后打开cmd建议用管理员权限定位到D:\Android\Sdk\cmdline-tools\latest\bin执行sdkmanager.bat platform-tools platforms;android-28 build-tools;28.0.3 ndk;21.4.7075429如果提示需要接受协议先执行sdkmanager.bat --licenses逐个输入y回车即可。安装过程取决于网络状况platform-tools和platforms不大NDK会有700MB左右建议预备好耐心。安装完验证一下sdkmanager.bat --list_installed确认输出里包含build-tools;28.0.3、platforms;android-28、ndk;21.4.7075429和platform-tools。2.3 如果已经装了Android Studio怎么补救如果你已经在用Android Studio那SDK Manager里也可以选这些版本。关键是SDK Manager默认只显示最新版本你得点右下角的“Show Package Details”才能展开历史版本列表。然后在SDK Platforms页签勾选Android 9.0 (Pie) / API 28SDK Tools页签勾选NDK (Side by side)展开选21.4.7075429再勾选“Show Package Details”在Build-Tools里选28.0.3这里容易出问题的是Android Studio往往自带了一个最新的Build-Tools比如34.0.0你如果只勾了最新版没勾28.0.3那Qt Creator检测时还是会报找不到build-tools 28.0.3因为Qt的构建脚本会在配置路径下按精确版本号去查找。2.4 设置ANDROID_HOME环境变量虽然Qt Creator里不强制要求你设这个变量但后续手动执行adb、打包、签名时有个环境变量会方便很多变量名ANDROID_HOME 变量值D:\Android\Sdk顺手把%ANDROID_HOME%\platform-tools也加进Path这样之后可以直接在cmd里敲adb命令。3. Qt 5.12.12 安装与 Qt Creator 配置里的细节3.1 安装器里的组件勾选漏选一步后面全是泪Qt的安装器和普通软件不太一样不是一路Next就完了。安装时选Custom模式然后在组件树里展开Qt 5.12.12至少勾选以下几项MinGW 7.3.0 32-bit或64-bit这是给Windows桌面调试用的编译器Android ARMv7对应32位安卓ABIAndroid ARM64-v8a对应64位安卓ABI如果你的目标设备是模拟器可以再勾一个Android x86但说实话现在模拟器性能都不差直接在真机上跑更爽。勾选MinGW时建议32位和64位都勾上虽然写Android程序用不到但有些情况下写个桌面小工具调试很实用。安装目录我习惯放在D:\Qt\Qt5.12.12路径简短没有空格后面省很多麻烦。3.2 Qt Creator里的Android设置页每一项都要手填启动Qt Creator后打开菜单工具 → 选项 → 设备 → Android这是整个搭建流程中最关键的一页。Qt Creator不会自动帮你探测所有路径很多时候需要手动填JDK location填C:\Java\jdk1.8.0_392按你实际JDK安装路径填。如果你装的是Adoptium路径里会带着Eclipse Adoptium的字样没关系只要指向JDK的根目录就行。Android SDK location填D:\Android\Sdk。这个就是SDK的根目录不是platform-tools目录不是cmdline-tools目录。Android NDK location填D:\Android\Sdk\ndk\21.4.7075429。注意要指到带版本号的子目录不是指到ndk这一层。刚安装完时这里往往显示黄色警告“No NDK found”手动指过去就正常了。OpenJDK vs Oracle JDK不必纠结只要是JDK 8就行。Qt Creator这里有个下拉框让你选JDK类型选错也不影响编译。填完后页面上会列出检测到的SDK版本和Build-Tools版本。在Build-Tools版本那列手动下拉选择28.0.3不要让它默认选最高版本。3.3 Kits面板里出现了什么才算配好了配置好Android页后切到工具 → 选项 → Kits在编译器标签页你应该能看到Qt 5.12.12安装器带过来的工具链。然后在已注册的套件Kits列表里会多出类似这样的项目Android for arm64-v8a (Clang 9)Android for armeabi-v7a (Clang 9)如果Kits列表里一个Android开头的套件都没有回去看Android设置页十有八九是NDK路径填错了层级或者SDK路径指到了D:\Android\Sdk\cmdline-tools。我遇到过一种情况是NDK路径指对了但Kits里显示红色警告“No compiler can produce code for this device”。这时候去检查NDK里的工具链文件是否存在——正常NDK r21d目录下应该有build\core\toolchains和toolchains两个目录如果你用的是某些精简版NDK或解压不完整就会出现这种幽灵套件。3.4 路径中文字符和空格问题再强调一次SDK路径、NDK路径、Qt安装路径、项目路径都别带中文和空格。Qt的构建脚本调用的是GCC和Make这些老牌工具对带空格路径的支持直到今天都算不上完美。你花三千字看完这篇教程但只要项目路径里有个中文文件夹名前面所有努力都有可能功亏一篑。4. 从 Kit 构建到真机安装的完整链路4.1 新建项目Kit选择是分水岭配置完成后新建一个Qt Widgets Application或Qt Quick Application在Kit选择页勾上Android for arm64-v8a也可以顺带勾上Android for armeabi-v7a。如果两个都勾构建时间会翻倍第一次环境验证阶段建议只勾arm64-v8a。创建好项目后左下角项目模式里能看到Android构建相关的设置默认的minSdkVersion一般是21Android 5.0、targetSdkVersion是28或29保持默认即可。4.2 首次构建Gradle是隐藏的“第二套环境”点构建按钮后Qt会先在项目文件夹下生成一个android-build目录然后调用Gradle去打包APK。这里有一个很大的隐藏坑Gradle本身需要下载。Qt 5.12.12内置的Gradle Wrapper会去下载指定版本的Gradle发行包比如gradle-5.5.1-all.zip。如果你的网络访问Gradle官方仓库不太好这一步会卡很久甚至直接超时。解决办法是手动下载这个zip包放到本地然后修改android-build\gradle\wrapper\gradle-wrapper.properties里的distributionUrldistributionUrlhttps\://services.gradle.org/distributions/gradle-5.5.1-all.zip改成本地文件路径distributionUrlfile\:///D:/gradle/gradle-5.5.1-all.zip改完再重新构建Gradle就不会去网上找了。这种方式在离线环境中也适用我第一次给一台不能连外网的机器部署时就是这么干的。Gradle本身下载完成后它还会去拉Android Gradle Plugin依赖包同样是在线下载。这个依赖如果一直拉不下来可以在android-build\build.gradle文件里把repositories仓库源换成国内可访问的镜像源不同国家和地区可用的仓库不一样这里就不展开说具体源了网上搜一下能找到很多现成的配置。4.3 APK生成与真机安装构建成功后APK文件会生成在项目目录\build\android-build\build\outputs\apk\debug\android-build-debug.apk这个APK用的是Qt自带的debug签名可以直接装在开发机上。连接真机前手机上先打开开发者选项和USB调试。很多国产手机还要在“USB配置”里选择“传输文件MTP”模式只充电模式adb识别不到。连上后打开命令行执行adb devices如果列表里显示设备的序列号并且状态是device那就一切正常。如果显示unauthorized看手机屏幕弹窗问“是否允许USB调试”点允许然后再执行一次adb devices。Qt Creator里的运行按钮会直接执行“构建 安装 启动”三步。如果一切顺利你的App就在手机上跑起来了。第一次看到这个画面的瞬间前面所有的折腾都值了。4.4 ABI取舍和包体积控制你可能会注意到在Qt Creator里同时勾选了armv7和arm64-v8a时生成的APK会包含两套代码体积直接翻倍。实际开发中如果App只面向主流机型只保留arm64-v8a就够用了。armv7主要覆盖一些老机型或低端设备x86基本只用模拟器。这个取舍可以在项目的.pro文件中手动控制也可以通过Qt Creator的Android构建设置里勾选ABI来完成。建议开发调试阶段只勾arm64-v8a节省构建时间发布前再根据目标用户群决定是否加入其他ABI。5. 高频报错排查这些坑我替你踩过了5.1 编译期报错从最烦人的开始说“Cant find build-tools version 28.0.3”这个报错的环境配置页里大概率显示Build-Tools是空的或者只有一个高版本。根因在于SDK里没装28.0.3Qt Creator按配置去找这个精确版本找不到就报错。解决方式回到第2.2节用sdkmanager补装或者在Android Studio的SDK Manager里勾选对应版本。如果已经装了但Qt Creator还是报错检查SDK路径是否指错了层级。“The SDK Build Tools revision (34.0.0) is too low for project :app”这个报错非常迷惑字面意思是build-tools版本太低但实际上你装的是最高版本。根因是Qt 5.12.12的Gradle插件太老它不认识比自己晚很多年的Build-Tools。解决方式还是装28.0.3并且确保Qt Creator选中它。“Toolchain error: None of the toolchains are compatible with the NDK”NDK版本或路径问题。如果你用的是r22以上版本几乎必现这个错。降级到r21d或者在设置页重新指到D:\Android\Sdk\ndk\21.4.7075429。“Failed to configure project :app. The Android Gradle plugin requires JDK 8”检查java -version如果输出是11或17说明系统当前JDK不对。Qt Creator有自己的JDK设置但Gradle子进程读的是环境变量JAVA_HOME。把JAVA_HOME改回JDK 8重启Qt Creator。“aapt2: error: ... Permission denied / zip file open error”一般是build-tools版本过新与SDK Platform版本不匹配导致。把build-tools锁到28.0.3后基本解决。如果还报错检查SDK目录是否放在了有权限限制的系统文件夹下比如C:\Program Files (x86)。“Could not find com.android.tools.build:gradle:3.5.4”或类似依赖拉不下来Gradle在下载Android Gradle Plugin依赖时网络失败。建议检查第4.2节的仓库源配置是否生效或者手动在浏览器中下载对应的jar包放进Gradle缓存目录也可以考虑在公司内网环境用共享的网络代理服务。总之要把依赖文件搞到本地Gradle能访问的地方。5.2 安装期报错手机连不上和装不上adb devices显示unauthorized手机端确认调试授权弹窗重新插拔USB或者执行adb kill-server adb start-server后重新插拔。INSTALL_FAILED_OLDER_SDK手机系统版本低于APK的minSdkVersion。Qt 5.12.12创建项目默认minSdkVersion是21Android 5.0如果你的手机还在更老的版本……说实话该换手机了。也可以手动把.pro文件中或构建参数里的minSdkVersion调低但Qt本身对老Android系统的支持有限不建议低于21。INSTALL_FAILED_UPDATE_INCOMPATIBLE手机上已经装了旧签名或不同签名的同包名应用。卸载后再装即可。INSTALL_FAILED_NO_MATCHING_ABISAPK里包含的ABI和手机CPU不支持匹配。比如你只构建了x86但真机是arm64。回到构建设置里勾上arm64-v8a重新构建。5.3 最容易误判的“环境损坏”类问题有一类报错让你以为SDK装坏了其实就是Qt Creator缓存了旧的配置。比如你改了JDK路径、NDK路径后Qt Creator界面显示正常但构建用的还是旧路径。这种情况先试完全退出Qt Creator删除项目目录下的build文件夹和.user后缀的用户配置文件重新打开工程并构建。还有一个常见的假损坏现象报错信息里出现两个ANDROID_HOME一个是你设的D:\Android\Sdk一个是系统里残留的其他路径。这种多重环境变量会让构建脚本疯掉。检查一下系统环境变量和用户环境变量里是不是都设了ANDROID_HOME只保留一个。最后一点不要同时开着Android Studio和Qt Creator去操作同一套SDK。两个IDE偶尔会互相锁文件尤其在做SDK组件更新的时候容易报出一些奇奇怪怪的IO异常。我就是因为这种低级问题白耗过一个下午。给你一个我的习惯做法每搭好一套开发环境把四件套的精确版本号记在项目的README里。以后换电脑、加同事、更新CI照着这个版本列表半小时就能把环境重建出来。比重新研究一遍SDK兼容性快得多。