企业官网建设流程全解析

我第一次搭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崩溃。
• NDK：r21d（版本号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 r21d

2.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 28
• SDK 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位安卓ABI
• Android 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一般是21（Android 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里的distributionUrl：

distributionUrl=https\://services.gradle.org/distributions/gradle-5.5.1-all.zip

改成本地文件路径：

distributionUrl=file\:///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 编译期报错：从最烦人的开始说

“Can't find build-tools version 28.0.3”

这个报错的环境配置页里大概率显示Build-Tools是空的，或者只有一个高版本。根因在于SDK里没装28.0.3，Qt 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是21（Android 5.0），如果你的手机还在更老的版本……说实话该换手机了。也可以手动把.pro文件中或构建参数里的minSdkVersion调低，但Qt本身对老Android系统的支持有限，不建议低于21。

INSTALL_FAILED_UPDATE_INCOMPATIBLE

手机上已经装了旧签名或不同签名的同包名应用。卸载后再装即可。

INSTALL_FAILED_NO_MATCHING_ABIS

APK里包含的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兼容性快得多。