在桌面端、移动端乃至嵌入式领域Qt 框架以其“一次编写到处编译”的强大跨平台能力始终是 C 图形界面开发的首选利器。然而当开发者希望将 Qt 应用部署到 Android 平台时往往会遇到环境搭建复杂、依赖项繁多、真机调试困难等一系列“拦路虎”。本文旨在提供一个从零开始的保姆级教程手把手带你完成 Qt 6.10.1 的安装并详细配置其 Android 开发环境覆盖桌面开发、Android 真机调试以及 Android 虚拟机AVD运行三种场景。无论你是 Qt 新手还是希望拓展移动端开发的 C 开发者都能通过本文获得一套完整、可复现的解决方案。1. 背景与核心概念在深入安装配置之前我们有必要厘清几个核心概念这有助于理解后续每一步操作的意义。Qt 是什么Qt 是一个跨平台的 C 应用程序开发框架。它不仅仅用于创建图形用户界面GUI还提供了网络、数据库、多线程、XML、OpenGL 等丰富的模块几乎涵盖了现代应用开发的所有需求。其核心优势在于“信号与槽”机制这是一种灵活且类型安全的对象间通信方式极大地简化了事件驱动编程。Qt for Android 的工作原理Qt 本身并不直接生成 Android 的原生 APK。当选择 Android 作为目标平台时Qt 的构建系统会执行以下关键步骤交叉编译使用 Android 平台特定的工具链如 NDK 中的编译器将你的 C/Qt 代码编译成适用于 ARM 或 x86 架构的本地库.so文件。Java 封装Qt 提供了一个名为QtActivity的 Java 类它继承自 Android 的Activity。这个QtActivity负责启动一个原生视图SurfaceView或TextureView并将你的 Qt/C 代码渲染到这个视图中。同时它还会处理 Android 的生命周期事件如暂停、恢复并将其转发给 Qt 应用。打包最终构建系统会将编译好的 C 库、必要的 Qt 库、QtActivity以及一个最小的 Android 应用框架包含AndroidManifest.xml等一起打包成一个标准的 APK 文件。因此配置 Qt for Android 的本质就是为 Qt 的构建系统提供一套完整的 Android 开发工具链SDK、NDK、JDK和构建工具CMake/QMake使其能够完成上述交叉编译和打包过程。为什么选择 Qt 6.10.1Qt 6 系列是当前的主线版本相较于 Qt 5 在模块架构、图形后端引入 RHI和性能上有显著改进。Qt 6.10 是一个长期支持版本LTS意味着它会获得长时间的错误修复和安全更新非常适合用于生产项目。选择最新的 LTS 版本能确保我们获得稳定的功能和新特性的支持。2. 环境准备与版本说明工欲善其事必先利其器。在开始安装 Qt 之前我们需要准备好所有必要的组件。请严格按照以下版本和路径建议操作这是避免后续各种诡异错误的关键。操作系统Windows 10/11 64位 或 macOS 10.15 或 Ubuntu 20.04/22.04 LTS。本文将以Windows 11为主要演示环境关键差异处会注明。核心组件清单Qt 安装程序Qt Online Installer。用于下载和安装 Qt 库及工具。Java Development Kit (JDK)提供编译 Android 应用所需的 Java 环境。必须使用 OpenJDK 11。Oracle JDK 或其他版本可能导致兼容性问题。Android Software Development Kit (SDK)包含构建、测试、调试 Android 应用所需的工具和平台库。Android Native Development Kit (NDK)一套允许你使用 C 和 C 代码开发 Android 应用的工具集。Qt 的交叉编译依赖它。Android 构建工具CMake和Ninja。Qt 6 默认使用 CMake 作为构建系统Ninja 作为后端速度更快。版本兼容性矩阵组件推荐版本说明Qt6.10.1选择msvc2019_64或mingw_64桌面套件以及android套件。JDKOpenJDK 11 (LTS)可从 Adoptium 或 Microsoft 下载。Android SDK命令行工具 (Command-line Tools)建议通过 Android Studio 安装或单独下载。Android NDK25.x 或 26.xQt 6.10 官方推荐 NDK 25。避免使用过新如 r27或过旧的版本。CMake3.29Qt 安装器通常会捆绑一个版本也可单独安装。Ninja1.11Qt 安装器通常会捆绑。重要路径规划 为了避免权限问题和路径混乱建议在非系统盘如D:\创建一个统一的开发环境目录例如D:\Dev。后续所有组件都安装在此目录下。D:\Dev\ ├── Java\ # JDK 安装目录 ├── Android\ # Android SDK/NDK 安装目录 └── Qt\ # Qt 安装目录在 macOS/Linux 下可以使用/Users/YourName/Development或/opt等目录。3. 分步安装与配置接下来我们按照依赖关系从底层到上层逐一安装和配置。3.1 安装 OpenJDK 11下载访问 Adoptium Eclipse Temurin 网站选择版本11 (LTS)根据你的系统选择安装包如 Windows 选择.msi macOS 选择.pkg。安装运行安装程序。关键步骤记下或自定义安装路径例如D:\Dev\Java\jdk-11。确保安装路径没有中文和空格。配置环境变量JAVA_HOME新建系统环境变量值为你的 JDK 安装路径如D:\Dev\Java\jdk-11。Path在系统环境变量Path中添加%JAVA_HOME%\bin。验证打开新的命令行终端CMD 或 PowerShell输入以下命令java -version应输出类似openjdk version 11.0.22的信息。同时检查javac命令是否可用。3.2 安装 Android SDK 与 NDK有两种主流方式通过 Android Studio 安装图形化推荐新手或使用独立的命令行工具。这里介绍更可控的命令行工具方式。下载命令行工具 访问 Android 开发者网站 下载适用于你系统的“Command line tools only”。例如 Windows 系统下载commandlinetools-win-*.zip。解压与放置 在D:\Dev\Android目录下创建一个子目录例如cmdline-tools。将下载的 ZIP 包解压你会得到一个cmdline-tools文件夹将其中的内容bin,lib,NOTICE.txt,source.properties复制到刚创建的D:\Dev\Android\cmdline-tools目录下。重要最终的sdkmanager.bat文件路径应为D:\Dev\Android\cmdline-tools\bin\sdkmanager.bat。配置环境变量ANDROID_HOME或ANDROID_SDK_ROOT新建系统环境变量值为D:\Dev\Android。Qt 主要认ANDROID_SDK_ROOT建议都设置。Path添加%ANDROID_SDK_ROOT%\cmdline-tools\bin和%ANDROID_SDK_ROOT%\platform-tools。使用 sdkmanager 安装组件 打开 PowerShell管理员权限依次执行以下命令# 接受必要的许可协议 sdkmanager --licenses # 安装平台工具和构建工具必须 sdkmanager platform-tools build-tools;34.0.0 # 安装 Android 平台API级别例如 34 对应 Android 14 sdkmanager platforms;android-34 # 安装 NDK关键这里安装 25.2.9519653 sdkmanager ndk;25.2.9519653 # 也可以安装 CMake 和 Ninja如果不想用 Qt 自带的 # sdkmanager cmake;3.22.1 ninja;1.11.1安装过程可能需要较长时间请保持网络通畅。安装完成后你的D:\Dev\Android目录结构应大致如下D:\Dev\Android\ ├── cmdline-tools\ ├── build-tools\34.0.0\ ├── ndk\25.2.9519653\ # 这就是 NDK 路径 ├── platforms\android-34\ └── platform-tools\记下 NDK 的完整路径例如D:\Dev\Android\ndk\25.2.9519653。3.3 安装 Qt 6.10.1这是核心步骤我们需要安装 Qt 库本身以及 Qt Creator IDE。下载在线安装器 访问 Qt 官网下载页面 选择 “Download the Qt Online Installer”。你需要注册一个 Qt 账户免费。运行安装器 登录后在 “Select Components” 页面展开Qt-Qt 6.10.1。桌面开发根据你的编译器选择。如果你使用 Visual Studio勾选MSVC 2019 64-bit。如果使用 MinGW勾选MinGW 11.2.0 64-bit。至少选择一个桌面套件用于在电脑上快速开发和测试。Android 开发勾选Android下的Android 6.10.1。安装器会自动识别已安装的 JDK、SDK、NDK如果路径正确旁边会显示绿色对勾。如果显示红色叉号可以点击右侧的...手动指定路径。开发工具确保Qt Creator 13.0.2被选中。也可以勾选Qt Creator 13.0.2 CDB Debugger Support用于 Windows 调试和Debugging Tools for Windows。附加库根据项目需要选择例如Qt 5 Compatibility Module、Qt Multimedia等。初学者可以暂时不选。选择安装路径建议安装到D:\Dev\Qt。安装路径同样不能有中文和空格。等待安装完成这是一个漫长的过程取决于网络速度和所选组件。3.4 在 Qt Creator 中配置 Android 套件安装完成后启动 Qt Creator。首次启动或需要手动配置 Android 环境。打开选项/设置Windows/Linux:Tools-Options...macOS:Qt Creator-Preferences...配置 Kits套件 左侧选择Devices-Android。JDK Location应自动检测到你的 JDK 11 路径。如果没有手动指向D:\Dev\Java\jdk-11。Android SDK Location指向D:\Dev\Android。Android NDK Location指向D:\Dev\Android\ndk\25.2.9519653。SDK Manager AVD Manager路径应自动填充。点击Apply。检查构建套件 左侧选择Kits。Qt Creator 应该已经自动检测并创建了至少两个套件Desktop Qt 6.10.1 MSVC2019 64bit用于桌面编译。Android Qt 6.10.1 Clang Multi-Abi用于 Android 设备编译。 点击 Android 套件确保其Device type为Android并且下面的Compiler、Debugger、Qt version都已正确识别没有黄色警告图标。如果Debugger显示为“None”可能需要点击Manage...来配置但通常 Qt Creator 会自动处理。至此所有底层环境和 Qt Creator 的配置已经完成。你可以创建一个简单的 Qt Widgets 应用在套件选择器中分别选择桌面套件和 Android 套件进行编译和运行初步验证环境是否正常。4. 创建并运行第一个 Android Qt 应用让我们通过一个完整的“Hello World”项目来验证整个 Android 开发流程。4.1 创建新项目在 Qt Creator 中点击File-New Project...。选择Application-Qt Widgets Application点击Choose...。输入项目名称例如HelloAndroidQt选择项目保存路径同样避免中文和空格。在Build System选择CMakeQt 6 默认。在Details页面基类选择QWidget。在Kit Selection页面关键步骤同时勾选你的桌面套件如Desktop Qt 6.10.1 MSVC2019 64bit和 Android 套件Android Qt 6.10.1 Clang Multi-Abi。这样项目将同时支持两个平台的构建。完成创建。4.2 修改界面并添加权限为了演示 Android 特性我们简单修改界面并添加一个网络权限。修改mainwindow.ui 在 Qt Creator 的设计模式下拖拽一个Label和一个Push Button到窗口上。将 Label 的文本改为Hello from Qt on Android!将 Button 的文本改为Get Network Info。保存。修改mainwindow.cpp 为按钮添加一个点击槽函数尝试获取网络信息仅作演示。// mainwindow.cpp #include mainwindow.h #include ui_mainwindow.h #include QNetworkInterface #include QMessageBox MainWindow::MainWindow(QWidget *parent) : QWidget(parent) , ui(new Ui::MainWindow) { ui-setupUi(this); // 连接按钮点击信号到槽函数 connect(ui-pushButton, QPushButton::clicked, this, MainWindow::onButtonClicked); } void MainWindow::onButtonClicked() { QString info; QListQNetworkInterface interfaces QNetworkInterface::allInterfaces(); for (const QNetworkInterface interface : interfaces) { if (interface.flags().testFlag(QNetworkInterface::IsUp) !interface.flags().testFlag(QNetworkInterface::IsLoopBack)) { info interface.humanReadableName() \n; } } QMessageBox::information(this, Network Interfaces, info.isEmpty() ? No active interface found. : info); }添加 Android 网络权限 Qt 项目通过一个特殊的android目录下的文件来配置 Android 清单。在项目根目录与CMakeLists.txt同级创建一个名为android的文件夹。在该文件夹内创建一个名为AndroidManifest.xml的文件内容如下?xml version1.0? manifest xmlns:androidhttp://schemas.android.com/apk/res/android packageorg.qtproject.example.HelloAndroidQt android:versionCode1 android:versionName1.0 uses-permission android:nameandroid.permission.INTERNET / application android:labelHelloAndroidQt android:icondrawable/icon activity android:nameorg.qtproject.qt.android.bindings.QtActivity android:labelHelloAndroidQt android:configChangesorientation|uiMode|screenLayout|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|keyboard|keyboardHidden|navigation|mcc|mnc|density android:screenOrientationunspecified android:launchModesingleTop android:themeandroid:style/Theme.Holo.Light intent-filter action android:nameandroid.intent.action.MAIN / category android:nameandroid.intent.category.LAUNCHER / /intent-filter meta-data android:nameandroid.app.lib_name android:value-- %%INSERT_APP_LIB_NAME%% --/ meta-data android:nameandroid.app.qt_sources_resource_id android:resourcearray/qt_sources/ meta-data android:nameandroid.app.repository android:valuedefault/ meta-data android:nameandroid.app.qt_libs_resource_id android:resourcearray/qt_libs/ meta-data android:nameandroid.app.bundled_qt_libs_resource_id android:resourcearray/bundled_qt_libs/ meta-data android:nameandroid.app.bundled_in_lib_resource_id android:resourcearray/bundled_in_lib/ meta-data android:nameandroid.app.bundled_in_assets_resource_id android:resourcearray/bundled_in_assets/ meta-data android:nameandroid.app.static_init_classes_resource_id android:resourcearray/static_init_classes/ meta-data android:nameandroid.app.native_libraries_resource_id android:resourcearray/native_libraries/ meta-data android:nameandroid.app.load_local_libs_resource_id android:resourcearray/load_local_libs/ meta-data android:nameandroid.app.load_local_jars_resource_id android:resourcearray/load_local_jars/ meta-data android:nameandroid.app.use_local_qt_libs_resource_id android:resourcearray/use_local_qt_libs/ meta-data android:nameandroid.app.qt_load_style android:valuestatic/ /activity /application /manifest注意package属性它定义了应用的唯一标识符应修改为你自己的域名反转格式。uses-permission android:nameandroid.permission.INTERNET /这一行就是我们添加的网络权限。4.3 构建与运行到桌面首先确保左下角的套件选择器选中的是你的桌面套件如Desktop Qt 6.10.1 MSVC2019 64bit。点击左下角的绿色运行按钮或按CtrlR。项目将使用桌面 Qt 库进行编译和运行弹出一个桌面窗口。点击按钮会弹出一个消息框显示网络接口信息。这证明我们的代码逻辑在桌面端是正常的。4.4 构建 APK 并运行到 Android 设备这是最关键的一步。切换套件将左下角的套件选择器切换到Android Qt 6.10.1 Clang Multi-Abi。连接 Android 设备真机使用 USB 数据线连接手机到电脑。在手机上开启“开发者选项”和“USB 调试”模式通常在“关于手机”中连续点击“版本号”可开启开发者选项。虚拟机 (AVD)如果你没有真机需要在 Qt Creator 中配置 AVD。在Tools-Options-Devices-Android页面点击AVD Manager按钮。在弹出的 Android Virtual Device Manager 窗口中点击Create Virtual Device选择一个设备定义如 Pixel 6然后选择一个系统镜像如 Android 14 API 34完成创建并启动它。运行到设备在 Qt Creator 中确保目标设备已识别在运行按钮右侧的下拉菜单中可以看到你的真机设备名称或 AVD 名称。点击绿色运行按钮。构建过程Qt Creator 会开始交叉编译。这个过程会比桌面编译慢因为它需要为多个 ABI如 arm64-v8a, armeabi-v7a, x86_64编译 Qt 库和你的代码。第一次构建会非常漫长因为需要编译整个 Qt for Android 的依赖库。请耐心等待。安装与运行构建成功后Qt Creator 会自动将 APK 安装到已连接的设备真机或虚拟机上并启动应用。你将在 Android 设备上看到与桌面端类似的界面。点击按钮应用会请求网络权限如果在 Android 6.0可能需要动态请求本例为简化在清单中声明并显示网络接口信息。恭喜至此你已经成功完成了 Qt 6.10.1 的安装并配置好了完整的 Android 开发环境实现了从桌面到 Android 设备的全流程开发。5. 常见问题与排查思路即使按照教程操作你也可能遇到一些问题。以下是高频问题及其解决方案。问题现象可能原因排查与解决思路Qt Creator 中 Android 套件显示黄色警告JDK/SDK/NDK 路径未正确配置或版本不兼容。1. 检查Tools-Options-Devices-Android中所有路径是否正确。2. 确认 JDK 是 OpenJDK 11 NDK 是 25.x。3. 重启 Qt Creator。构建 Android 项目时CMake 报错找不到工具链NDK 路径错误或 NDK 版本不被 Qt 支持。1. 在 Qt Creator 的 Android 配置中重新选择 NDK 路径。2. 尝试使用sdkmanager安装 Qt 官方推荐的 NDK 25.2.9519653。3. 检查项目.user文件是否包含了错误的旧路径。编译过程中报错Cannot find -lGLESv2或类似链接错误Android 构建工具链或平台版本不匹配。1. 确保在sdkmanager中安装了正确的platforms;android-34和build-tools;34.0.0。2. 在项目的CMakeLists.txt或.pro文件中检查android-ndk和android-sdk的路径变量。APK 安装到手机失败手机已有同名应用签名冲突、存储空间不足、USB 调试未开启。1. 卸载手机上的旧版本应用。2. 检查手机存储空间。3. 确认手机“开发者选项”中的“USB 调试”已开启并且连接模式是“文件传输”或“MTP”。4. 在电脑设备管理器中检查 ADB 驱动是否正常。应用在手机上启动后立即崩溃C 库缺失、权限未声明、ABI 不匹配。1. 检查AndroidManifest.xml是否声明了所有必要的权限如网络、存储。2. 查看Logcat输出Qt Creator 的Android标签页或使用adb logcat命令寻找Fatal signal或java.lang.UnsatisfiedLinkError等关键错误信息。3. 确保 Qt 安装时勾选了对应的 Android ABI 组件。Qt Creator 无法识别已连接的 Android 设备ADB 未运行、驱动问题、设备未授权。1. 命令行执行adb devices查看设备列表。如果显示unauthorized在手机上弹出的“允许USB调试”对话框中点击确认。2. 重启 ADBadb kill-server然后adb start-server。3. 更换 USB 数据线或端口。构建速度极慢尤其是第一次正常现象。Qt for Android 需要编译大量静态库。耐心等待首次构建完成。后续增量构建会快很多。可以喝杯咖啡。错误This application failed to start because no Qt platform plugin could be initialized在桌面运行时缺少 Qt 的平台插件如 windows、minimal。在 Android 上通常是 APK 打包时插件未正确包含。桌面检查环境变量QT_QPA_PLATFORM_PLUGIN_PATH或确保 Qt 的plugins/platforms目录在可执行文件路径中。Android此错误在 Android 上较少见若出现检查构建输出确认所有 Qt 插件如图形后端qminimal.so,qoffscreen.so是否被打包进 APK。6. 最佳实践与工程建议成功运行第一个应用只是起点。为了高效、稳定地进行 Qt Android 开发请遵循以下建议路径与版本管理绝对路径无中文空格这是铁律。JDK、Android SDK、NDK、Qt、项目路径全部遵守。版本固定在团队项目中使用sdkmanager安装特定版本的 SDK/NDK/构建工具并将版本号写入项目文档或脚本中避免因工具链升级导致构建失败。使用环境变量正确配置JAVA_HOME,ANDROID_SDK_ROOT,ANDROID_NDK_ROOT环境变量让 Qt Creator 和命令行工具都能自动识别。项目配置清晰的CMakeLists.txt合理组织find_package(Qt6),target_link_libraries等指令。将 Android 特定的配置如权限、图标、应用名称放在android目录下的文件中与桌面配置隔离。分离平台相关代码使用#ifdef Q_OS_ANDROID宏来编写 Android 平台特有的代码如访问传感器、处理返回键。#ifdef Q_OS_ANDROID // Android-specific code QJniObject activity QtAndroid::androidActivity(); #else // Desktop-specific code #endif调试与日志善用 Qt Creator 的 Android 输出面板它集成了logcat可以过滤Qt,DEBUG等标签是排查运行时问题的首要工具。使用qDebug()、qInfo()、qWarning()、qCritical()这些输出在 Android 的logcat中对应不同的日志级别便于追踪程序流。远程调试Qt Creator 支持在 Android 设备上进行 C 源码级调试。确保构建配置为Debug模式并在运行配置中启用调试器。性能与包体积优化选择正确的 Qt 模块在 Qt 安装时和项目的CMakeLists.txt中只链接项目实际用到的模块避免引入不必要的库增大 APK 体积。ABI 过滤默认会为arm64-v8a,armeabi-v7a,x86_64,x86等多个 ABI 生成 so 库。如果仅针对现代手机可以在项目的CMakeLists.txt或 Qt Creator 的构建设置中只选择arm64-v8a能显著减少 APK 大小。使用 Android App Bundle (AAB)对于发布到 Google Play可以配置生成 AAB 格式商店会根据用户设备动态分发优化后的 APK。发布准备应用签名调试版本使用默认调试密钥。发布前必须使用自己的密钥库对 APK 进行签名。可以在 Qt Creator 的项目运行设置中配置发布密钥。图标与资源在android/res目录下提供不同分辨率的drawable图标和mipmap资源。测试务必在多种 Android 版本和屏幕尺寸的真机上进行测试虚拟机无法完全模拟所有硬件行为如传感器、GPU 驱动差异。通过本教程你已经搭建起了一个坚实的 Qt for Android 开发环境并掌握了从创建、编码、构建到调试的基本工作流。环境配置是开发过程中最磨人但最重要的一环一旦打通后续就可以专注于 Qt/C 本身的业务逻辑开发享受跨平台带来的高效与便利。在下一部分我们将深入探讨更高级的主题例如 JNI 交互、调用 Android 原生 API、处理 Android 生命周期、UI 适配以及性能优化技巧。