企业官网建设流程全解析

新手搞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环境，本质上要搞定的是三样东西：JDK（Java开发工具包）、Android SDK（Android软件开发工具包）和NDK（原生开发工具包）。这三者之间存在严格的版本兼容关系，不是随便装个最新版就能跑起来的。

1.1 版本兼容矩阵：JDK、SDK、NDK怎么选才不吵架

先看QT官方和各工具链的命令行要求。QT 5.15.2在Windows上做Android开发，默认用的是Gradle构建系统，而Gradle本身对JDK版本有明确的兼容范围。我这里实测过两套组合：

这套版本组合不是我凭空想出来的，是踩了无数坑之后定下来的。最典型的教训是：刚开始图新鲜装了JDK 17，结果Gradle直接报“Unsupported class file major version 61”，后面换回JDK 8就正常了。NDK同理，装了最新的r25，QT编译时报“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 8

JDK的选择是最容易被忽略的环节，因为这玩意儿太常见，随手装个最新版总觉得没问题。但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环境变量，光是安装器自动配置的不够。

具体配置步骤：

1. 右键“此电脑” → 属性 → 高级系统设置 → 环境变量
2. 在“系统变量”区域点击“新建”
3. 变量名填JAVA_HOME，变量值填JDK的安装路径，比如D:\Java\jdk1.8.0_281
4. 找到Path变量，双击编辑，新增一条%JAVA_HOME%\bin
5. 打开命令提示符，输入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或34，QT 5.15.2默认targetSdkVersion比较低，API Level太高会出现一些兼容性告警，API 30是最稳的。

设置ANDROID_HOME环境变量：

1. 系统变量中新建ANDROID_HOME，变量值填D:\Android\sdk
2. 在Path中添加%ANDROID_HOME%\platform-tools
3. 命令行输入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页面里，需要配置三块内容：

1. Devices（设备）：这步是让QT Creator识别Android设备。点击“Add”选择“Android Device”，设备ID那一栏填1就行（默认自动生成的设备ID）。重点是最后的“Device”类型选择“Generic Android”，这个不能选错。

2. Android（安卓）：这是最关键的一页。在“SDK Manager”里配置Android SDK路径，填D:\Android\sdk。在这一页的底部分别设置：

   • JDK路径：D:\Java\jdk1.8.0_281
   • Android SDK路径：D:\Android\sdk
   • Android NDK路径：D:\Android\sdk\ndk\21.4.7075529

3. 编译器（Compilers）：QT Creator会自动扫描系统里的编译器。如果没识别出来，可以在“C++”栏手动添加，C编译器路径指向NDK里的toolchains\llvm\prebuilt\windows-x86_64\bin\clang.exe，C++编译器同理指向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、依赖库等。这个过程在国内网络环境下可能非常煎熬，常见的就是卡在某个依赖下载上，进度条死活不动。

实测下来有两个办法能缓解：

1. 手动下载Gradle发行版，放到C:\Users\<你的用户名>\.gradle\wrapper\dists\gradle-x.x-bin目录下，QT会自动识别已经下载好的文件。
2. 配置阿里云或腾讯云的Maven镜像，修改工程目录下的build.gradle文件，把google()和mavenCentral()替换成国内可访问的镜像地址。

我第一次构建等了将近40分钟，中间还失败了几次，后来加大内存和超时时间才顺利通过。具体做法是在gradle.properties里加几行：

org.gradle.daemon=true org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m org.gradle.parallel=true

构建成功后会生成一个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驱动没装对。

排查步骤：

1. 命令提示符输入adb devices，看有没有输出设备序列号。
2. 如果没有输出，说明驱动有问题，去手机厂商官网下载对应USB驱动，或者用Windows自动更新搜索驱动。
3. 如果输出设备序列号但还是连接不上，检查手机是否弹出“允许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设备上。