新手搞QT往Android上搬最头疼的不是代码而是环境。尤其是QT 5.15.2这个版本卡在JDK、SDK、NDK的版本匹配上一不留神就是一堆莫名其妙的报错。我前前后后在Windows 10上配过好几台机器踩遍了各种坑这次干脆把整个流程完整记下来从版本选择到环境变量从QT Creator配置到真机调试一步不落。如果你正要拿QT 5.15.2做Android开发这份保姆级教程应该能帮你少走不少弯路。先说清楚这套配置的核心痛点QT 5.15.2是LTS版本本身很稳但它对工具链的版本要求非常死板——JDK用错了直接提示Gradle版本不支持NDK版本太高会报一堆链接错误SDK没搞对连设备都认不出来。这篇文章就是围绕这三个组件的版本选择和配置来写的适合刚接触QT Android开发、以及被环境问题折磨到想摔键盘的开发者。1. 整体方案选型为什么QT 5.15.2要配这套工具链QT 5.15.2不是最新版本但它是很多人还在用的稳定版正好卡在Qt 5和Qt 6交替的过渡期。Windows 10上给QT配Android环境本质上要搞定的是三样东西JDKJava开发工具包、Android SDKAndroid软件开发工具包和NDK原生开发工具包。这三者之间存在严格的版本兼容关系不是随便装个最新版就能跑起来的。1.1 版本兼容矩阵JDK、SDK、NDK怎么选才不吵架先看QT官方和各工具链的命令行要求。QT 5.15.2在Windows上做Android开发默认用的是Gradle构建系统而Gradle本身对JDK版本有明确的兼容范围。我这里实测过两套组合组件推荐版本原因JDK1.8.0_281 或 11.0.xQT 5.15.2的Gradle插件对JDK 8支持最好JDK 11也试过可以Android SDKAPI Level 30或31平台工具和构建工具版本要和Gradle插件匹配Build-Tools30.0.3老版本稳定和QT 5.15.2的兼容性最好NDKr21e (21.4.7075529)QT 5.15.2官方默认NDK版本r23以上容易报错Gradle3.5.4QT自带不要手动升级QT 5.15.2内部锁定版本这套版本组合不是我凭空想出来的是踩了无数坑之后定下来的。最典型的教训是刚开始图新鲜装了JDK 17结果Gradle直接报“Unsupported class file major version 61”后面换回JDK 8就正常了。NDK同理装了最新的r25QT编译时报“clang: error: linker command failed with exit code 1”后来查资料才发现QT 5.15.2根本只能认r21系列。1.2 为什么要选Windows 10而不是其他系统如果你问QT Android开发是不是必须用Windows那肯定不是Linux和macOS都行。但现实情况是很多人主力机就是Windows 10换系统成本太高。Windows 10上配置QT Android环境的好处是驱动生态完善手机厂商的USB驱动基本都支持而且QT Creator在Windows上的表现一直很稳定。坏处是环境变量配置比Linux麻烦路径分隔符、权限问题也更容易踩坑。这套方案在Windows 10专业版和企业版LTSC 2021上都验证过系统版本不要太老或太新1909及以上都没问题。Windows 11也能用但QT 5.15.2官方没有在Windows 11上做过完整测试真机上家驱动可能有兼容性问题。1.3 方案优势为什么不上Qt 6这个问题肯定有人会问都2025年了为什么还要配QT 5.15.2原因很简单很多项目是在QT 5.15.2上开发的代码里有依赖老模块的地方直接迁到Qt 6要改的东西太多。而且QT 5.15.2是LTS版本意味着有长期维护补丁对于不想折腾、只求稳定的项目来说它就是最合理的选择。如果你是从零开始的新项目确实可以考虑Qt 6但如果你手里已经有QT 5.15.2的工程代码照着这篇文章配环境就是最省事的路径。2. 环境准备JDK、SDK、NDK的下载安装与避坑这部分是整个教程的重头戏也是翻车率最高的地方。版本和安装顺序很重要建议严格按照下面的步骤来操作不要跳步。2.1 JDK安装版本一定要卡在JDK 8JDK的选择是最容易被忽略的环节因为这玩意儿太常见随手装个最新版总觉得没问题。但QT 5.15.2的Android构建链路就是吃JDK 8这一套。我建议直接去Oracle官网下载jdk-8u281-windows-x64.exe或者用OpenJDK 8都行关键是大版本必须是8。安装JDK时注意两点。第一安装路径不要有中文和空格比如不要装到C:\Program Files\Java\jdk1.8.0_281这种带空格的路径虽然平时Java开发问题不大但QT Creator调用Gradle时偶尔会因为路径解析出问题建议装到D:\Java\jdk1.8.0_281。第二装完之后一定要手动配置JAVA_HOME环境变量光是安装器自动配置的不够。具体配置步骤右键“此电脑” → 属性 → 高级系统设置 → 环境变量在“系统变量”区域点击“新建”变量名填JAVA_HOME变量值填JDK的安装路径比如D:\Java\jdk1.8.0_281找到Path变量双击编辑新增一条%JAVA_HOME%\bin打开命令提示符输入java -version能看到版本号说明配置成功验证的时候注意如果命令行里显示的是其他版本比如之前装过别的JDK说明Path变量的顺序有问题需要把%JAVA_HOME%\bin移到前面去。2.2 Android SDK下载不用装Android Studio但要装Platform-Tools很多教程会让人去下载整个Android Studio然后从里面提取SDK。但说实话如果你只是为了做QT Android开发完全没必要装一个一两GB的IDE直接用命令行工具版Command Line Tools就够了。Android SDK的下载地址是官方提供的有“commandlinetools-win.zip”这个包。下载后解压到一个好记的位置建议用短路径比如D:\Android\sdk。解压出来后要手动跑几条命令来安装必要组件cd D:\Android\sdk\cmdline-tools\bin sdkmanager.bat platform-tools platforms;android-30 build-tools;30.0.3这里要注意第一次运行sdkmanager.bat可能会提示让你接受License输入y确认即可。如果在国内网络环境下下载特别慢或者超时建议用国内镜像源或者多试几次断点续传逻辑还是有的。装完后在SDK目录下会生成platform-tools、platforms、build-tools这几个子目录。这里经验是不要装最新的API 33或34QT 5.15.2默认targetSdkVersion比较低API Level太高会出现一些兼容性告警API 30是最稳的。设置ANDROID_HOME环境变量系统变量中新建ANDROID_HOME变量值填D:\Android\sdk在Path中添加%ANDROID_HOME%\platform-tools命令行输入adb --version验证能正常显示版本说明配置成功2.3 NDK安装版本指定r21e不要贪新NDK是整个环境里最容易出幺蛾子的东西没有之一。QT 5.15.2的Android工程编译时会调用NDK里的clang交叉编译工具链。NDK版本和QT的匹配逻辑很简单QT 5.15.2在官方网站上明确标注的支持范围就是NDK r21系列我用的就是r21e。有两种方式获取NDK r21e。第一种如果上面已经装好了SDK直接用sdkmanager来装sdkmanager.bat ndk;21.4.7075529这里21.4.7075529就是r21e的具体版本号装好后会在SDK目录下生成ndk\21.4.7075529文件夹。第二种方式去官网直接下载NDK的zip包下载地址里带r21e字样的那个包解压到D:\Android\sdk\ndk\21.4.7075529目录下。需要注意的是QT Creator在配置NDK路径时认的是NDK版本的根目录比如D:\Android\sdk\ndk\21.4.7075529而不是D:\Android\sdk\ndk。如果填错层级QT Creator会报“NDK directory does not contain a valid toolchain”。3. 核心配置QT Creator里的Android环境设置与首次构建现在三个基础组件都装好了A_HOME和JAVA_HOME也配好了接下来就是打开QT Creator把Android的环境变量和路径告诉它。3.1 QT Creator中配置Kits关键路径一个都不能错打开QT Creator建议用和QT 5.15.2配套的版本比如4.13以上都行依次点击“工具”→“选项”→“Kits”也有的版本显示为“套件”。在Kits页面里需要配置三块内容Devices设备这步是让QT Creator识别Android设备。点击“Add”选择“Android Device”设备ID那一栏填1就行默认自动生成的设备ID。重点是最后的“Device”类型选择“Generic Android”这个不能选错。Android安卓这是最关键的一页。在“SDK Manager”里配置Android SDK路径填D:\Android\sdk。在这一页的底部分别设置JDK路径D:\Java\jdk1.8.0_281Android SDK路径D:\Android\sdkAndroid NDK路径D:\Android\sdk\ndk\21.4.7075529编译器CompilersQT Creator会自动扫描系统里的编译器。如果没识别出来可以在“C”栏手动添加C编译器路径指向NDK里的toolchains\llvm\prebuilt\windows-x86_64\bin\clang.exeC编译器同理指向clang.exe。配置完不要急着点确定先把QT Creator重启一遍确保环境变量生效。这一步其实很多人会忽略结果路径明明填对了QT Creator就是读不到一重启就好了。3.2 检查QT 5.15.2是否安装Android构建模块QT 5.15.2在安装时是可以选择模块的如果你当时没有勾选Android相关的模块后面就算环境变量配得再完美也没用。检查方法很简单看QT安装目录下有没有Android相关文件夹。正常情况下QT 5.15.2的安装路径中应该有一个目录叫android_armv7或类似的像这样D:\Qt\Qt5.15.2\5.15.2\android_armv7如果没看到这种目录说明安装时漏掉了Android模块。解决办法是打开QT安装器MaintenanceTool.exe选择“添加或移除组件”在QT 5.15.2分支下勾选“Android”相关组件等它下载完就行。这一步是很多人配置了半天QT Creator里没有Android Kit可选的根本原因不是版本不对是压根没装Android模块。3.3 首次构建Android工程Gradle下载与首次编译环境配置完成后新建一个最简单的QWidget工程然后在构建套件Kit里选择“Android”相关的套件比如“Android for arm64-v8a”或者“Android for armeabi-v7a”。第一次点击构建时QT会在后台把构建任务交给Gradle此时会触发大量自动下载包括Gradle本身、Android Gradle Plugin、依赖库等。这个过程在国内网络环境下可能非常煎熬常见的就是卡在某个依赖下载上进度条死活不动。实测下来有两个办法能缓解手动下载Gradle发行版放到C:\Users\你的用户名\.gradle\wrapper\dists\gradle-x.x-bin目录下QT会自动识别已经下载好的文件。配置阿里云或腾讯云的Maven镜像修改工程目录下的build.gradle文件把google()和mavenCentral()替换成国内可访问的镜像地址。我第一次构建等了将近40分钟中间还失败了几次后来加大内存和超时时间才顺利通过。具体做法是在gradle.properties里加几行org.gradle.daemontrue org.gradle.jvmargs-Xmx2048m -XX:MaxPermSize512m org.gradle.paralleltrue构建成功后会生成一个APK文件路径一般在build\outputs\apk\debug\下。到这里环境配置的部分就算完成了。4. 常见问题与排查技巧实录哪怕你完全按照上面的步骤来依然可能碰到一些小问题下面列几个我在实际操作中遇到的典型报错和对应的排查方法。4.1 编译时报“NDK not configured”这个提示出现在构建时颜色通常是红色非常扎眼。一般原因有两个NDK的路径没有正确填到QT Creator里或者SDK和NDK的路径里有空格导致工具链无法调用。排查思路重新核对Kits → Android页面里的NDK路径确认指向的是...\ndk\21.4.7075529这一级。检查安装路径是否带空格如果之前装在了D:\Android Tools\这种路径下建议卸载重装到无空格路径。4.2 APK能构建但安装到手机上闪退闪退问题是Android开发最常见的坑之一QT环境引发的闪退主要是so库没打包进去。在构建时QT会生成多架构的so文件如果你在Kit里选了arm64-v8a但实际手机是老旧的32位处理器就会找不到对应so导致崩溃。解决办法是在构建APK时把支持的ABI都勾上或者至少明确你手机的架构。查看手机架构的方法adb shell getprop ro.product.cpu.abi另外QT 5.15.2默认编译的是Debug版如果手机上跑的是Release版某些调试接口不可用也会导致闪退这个要注意区分。4.3 设备列表里没有手机手机通过USB连接电脑同时打开了开发者模式和USB调试但QT Creator的Devices页面就是看不到设备。这个问题90%是USB驱动没装对。排查步骤命令提示符输入adb devices看有没有输出设备序列号。如果没有输出说明驱动有问题去手机厂商官网下载对应USB驱动或者用Windows自动更新搜索驱动。如果输出设备序列号但还是连接不上检查手机是否弹出“允许USB调试”的授权框需要在手机上点击允许。这里有个冷门但常见的坑有些Windows 10版本没有自动安装MTP驱动导致USB调试接口不受系统识别。装上厂商驱动后重启一次就解决了。4.4 Gradle构建超时或下载卡死这跟上文提到的一样实质上就是网络问题。除了设置镜像外还可以手动把Gradle的下载直接放到.gradle目录下面。另外还有一个小技巧是切换arm64-v8a和armeabi-v7a时Gradle缓存会失效重新构建看着像卡住了其实是缓存重建等一会儿就好。5. 最后再分享一个个人经验环境配置这件事最忌讳的就是“我每个组件都装最新的应该没问题”。在我陪跑过的十几个环境里凡是出问题的无一例外都是版本太新导致的。QT 5.15.2这套组合拳要求的是匹配不是性能。JDK 8、SDK API 30、NDK r21e这三个版本号希望你记在心里别让它们在未来的某一天再次找你麻烦。还有一个小细节如果以后你换了电脑把整套SDK和NDK目录整个拷过去再把环境变量路径改好QT Creator重新指定一下路径就行了不需要重新下载。希望这份保姆级教程能帮你少走一些弯路顺利把QT跑在Android设备上。