在桌面端、移动端乃至嵌入式领域进行跨平台开发时Qt 框架以其“一次编写到处编译”的特性始终是 C 开发者的重要选择。随着 Qt 6 系列的不断演进其对 Android 平台的支持也日趋完善和稳定。然而从 Qt 的安装、Android 开发环境的搭建到最终在真机或虚拟机上成功运行一个“Hello World”应用这个过程对于新手甚至有一定经验的开发者来说都可能充满“坑点”——环境变量冲突、SDK 版本不匹配、NDK 路径错误、虚拟机启动失败等问题层出不穷。本文将为你提供一份从零开始的保姆级教程详细拆解Qt 6.10.1的安装以及为 Android 开发配置完整环境的全过程。无论你是想在 Windows 桌面端开发还是希望将应用部署到 Android 真机或模拟器都能在这里找到清晰的步骤和避坑指南。教程内容涵盖 Qt 在线安装器的使用、Android SDK/NDK 的独立配置、Qt Creator 中的关键设置并最终引导你成功编译并运行一个简单的 Qt Widgets 应用到 Android 设备上。1. 核心概念与环境全景图在开始动手之前理解 Qt 进行 Android 开发所依赖的“技术栈”至关重要。这能帮助你在遇到问题时快速定位是哪个环节出了差错。Qt 是什么Qt 是一个跨平台的 C 应用程序开发框架。它提供了丰富的 GUI 控件、网络、数据库、多媒体等模块允许开发者使用一套代码库为 Windows、macOS、Linux、Android、iOS 等平台构建应用程序。Qt 6 是其最新的主要版本系列带来了模块化、性能提升和对现代 C 更好的支持。Android 开发需要哪些组件当 Qt 以 Android 为编译目标时它本质上充当了一个“桥梁”或“胶水层”。你的 C/Qt 代码并不会直接编译成 Android 可执行文件而是需要经过以下组件的协同工作Qt 库提供核心功能需要被交叉编译为 Android (ARM/x86) 架构的库文件。Android NDK (Native Development Kit)这是关键。NDK 提供了将 C/C 代码编译成 Android 可用的原生库.so文件的工具链如clang。Qt 的 Android 构建系统依赖于 NDK。Android SDK (Software Development Kit)提供构建、测试和调试 Android 应用所需的工具如adb(Android Debug Bridge)、apkanalyzer、以及管理虚拟设备 (AVD) 的avdmanager。Java JDK (Java Development Kit)虽然你的核心逻辑是 C但一个 Android 应用 (APK) 的包装层仍然是一个 Java/Kotlin 应用外壳。构建这个外壳生成最终的 APK 文件需要 JDK。通常Android Studio 会自带一个合适的 JDK (JRE)但 Qt 构建过程也可能需要指定一个独立的 JDK。构建工具主要是gradle。Qt 使用gradle来编排构建流程将你的 C 库、Qt 库、Java 外壳以及资源文件打包成最终的 APK。Qt Creator 的角色Qt Creator 是 Qt 官方推荐的集成开发环境 (IDE)。它集成了对上述所有组件的配置界面并能自动化处理很多复杂的构建步骤。本教程将主要基于 Qt Creator 进行配置和开发。目标环境说明本文演示环境为Windows 11但核心步骤和原理在 macOS 和 Linux 上同样适用仅有路径和安装包形式的差异。我们将安装Qt 6.10.1的在线安装版本并配置其支持 Android 开发。2. 环境准备与软件下载工欲善其事必先利其器。请确保你的电脑有足够的磁盘空间建议预留 20GB 以上并准备好下载以下软件。2.1 下载 Qt 在线安装器我们不推荐下载庞大的离线安装包在线安装器更灵活可以选择所需的组件。访问 Qt 官方下载页面通常为https://www.qt.io/download-open-source。找到 “Download the Qt Online Installer” 部分根据你的操作系统下载对应的安装程序。对于 Windows通常是qt-unified-windows-x64-online.exe。可选但推荐注册一个 Qt 账号。虽然开源版本可以免费使用但安装器启动时需要登录。你可以选择注册也可以稍后在安装器界面跳过部分版本允许。2.2 准备 Android 开发环境独立于 Qt为了避免与 Qt 安装器自带的旧版本 Android 工具产生冲突并获得更大的控制权我们选择手动配置 Android SDK 和 NDK。下载 Android Studio前往 Android 开发者官网 (developer.android.com/studio)下载 Android Studio 安装程序。我们主要目的不是用它开发而是用它来方便地下载和管理 SDK/NDK。安装 Android Studio运行安装程序按照向导进行。在 “Install Type” 页面选择 “Standard” 即可。安装完成后先不要启动。2.3 确认或安装 Java JDK打开命令提示符 (cmd)输入java -version。如果显示版本信息如openjdk version “17.0.xx”则说明已安装。Qt 6.10.1 通常需要 JDK 11 或 17。如果未安装可以去 Oracle 官网或 Adoptium 网站下载 OpenJDK 17 并安装。请记住 JDK 的安装路径例如C:\Program Files\Eclipse Adoptium\jdk-17.0.xx-hotspot。3. 安装 Qt 6.10.1 与桌面组件现在我们开始安装 Qt 框架本身。3.1 运行 Qt 在线安装器双击下载好的qt-unified-windows-x64-online.exe。登录你的 Qt 账号或跳过登录。在安装向导中选择 “Skip” 或 “Next” 直到进入组件选择页面。此处需要仔细选择。3.2 选择安装路径和组件安装路径建议选择一个没有空格和中文的路径例如D:\Qt。这能避免后续可能出现的各种路径解析问题。选择 Qt 版本在 “Qt” - “Qt 6.10.1” 下展开树形列表。你必须勾选以下核心组件MSVC 2022 64-bit这是用于在 Windows 桌面端开发和调试的编译器套件。即使你做 Android 开发也建议安装方便快速在桌面测试逻辑。Android(或Qt 6.10.1 for Android)这是关键这个组件包含了 Qt 库针对 Android 平台的预编译文件以及必要的构建工具。Sources和Qt Debug Information Files可选但有助于调试和阅读源码。Qt Creator务必勾选这是我们的主力 IDE。Developer and Designer Tools下的MinGW xx.x.x 64-bit可选这是另一个 Windows 下的 GCC 编译器套件如果你不需要可以省略以节省空间。点击 “Next”同意许可协议开始安装。这个过程会下载数 GB 的文件耗时取决于你的网速。3.3 验证桌面安装安装完成后从开始菜单或安装路径启动 Qt Creator。点击 “文件” - “新建文件或项目”。选择 “Application” - “Qt Widgets Application”点击 “Choose...”。给项目起名如TestDesktop选择一个无中文空格的路径。在 “Kit Selection” 页面确保选择了Desktop Qt 6.10.1 MSVC2022 64bit这个套件。完成向导点击左下角的绿色三角运行按钮或按CtrlR。如果成功弹出一个空白窗口恭喜你Qt 桌面环境安装成功4. 配置 Android 开发环境SDK, NDK, JDK这是整个流程中最容易出错的一步。我们将使用 Android Studio 来获取正确的组件然后在 Qt Creator 中配置。4.1 使用 Android Studio 下载 SDK 和 NDK启动 Android Studio。首次启动会进入设置向导。在 “Welcome” 界面点击右下角的 “More Actions” - “SDK Manager”。在弹出的 “SDK Platforms” 选项卡中选择你希望开发应用所面向的 Android 版本。对于 Qt 开发建议选择一个比较普及且稳定的版本例如 “Android 11.0 (R)” 或 “Android 12.0 (S)”。勾选后点击 “Apply” 进行安装。切换到 “SDK Tools” 选项卡。这里需要勾选以下几项Android SDK Build-Tools选择最新的稳定版本如 34.0.0。Android SDK Command-line Tools (latest)必须安装。Android SDK Platform-Tools包含adb等关键工具必须安装。NDK (Side by side)这是重中之重勾选并选择版本。Qt 6.10.1 官方推荐使用 NDK r25c。你可以在列表中选择25.2.9519653或相近版本。如果列表中没有你可能需要从官网单独下载。请务必记录 NDK 的完整路径通常位于[Android SDK 路径]\ndk\[版本号]例如C:\Users\YourName\AppData\Local\Android\Sdk\ndk\25.2.9519653。CMake和LLDB可选但建议安装用于原生代码的构建和调试。点击 “Apply” 开始下载安装。完成后记下Android SDK 的根路径通常位于C:\Users\YourName\AppData\Local\Android\Sdk。4.2 在 Qt Creator 中配置 Android 套件打开 Qt Creator点击菜单栏的 “工具” - “选项” (在 macOS 上是 “Qt Creator” - “Preferences”)。在左侧找到 “设备” - “Android”。在右侧面板中你需要设置三个路径JDK 位置点击 “浏览”定位到你之前安装的 JDK 根目录例如C:\Program Files\Eclipse Adoptium\jdk-17.0.xx-hotspot。Android SDK 位置点击 “浏览”定位到你的 Android SDK 根目录例如C:\Users\YourName\AppData\Local\Android\Sdk。Android NDK 位置点击 “浏览”定位到你刚刚安装的 NDK 目录例如C:\Users\YourName\AppData\Local\Android\Sdk\ndk\25.2.9519653。点击 “应用”。Qt Creator 会自动检测 SDK 下的构建工具和平台工具。如果路径正确下方会显示检测到的版本信息。切换到 “Kits” 选项卡。你应该能看到一个自动配置好的 Android 套件名字可能类似于Android Qt 6.10.1 Clang arm64-v8a或Android Qt 6.10.1 Clang armeabi-v7a。这表示 Qt Creator 已经成功识别了 Android 开发环境。5. 创建并配置 Android 项目环境配置好后我们来创建一个真正的 Android 项目。5.1 新建 Qt Android 项目在 Qt Creator 中点击 “文件” - “新建文件或项目”。依然选择 “Application” - “Qt Widgets Application”。虽然 Qt Quick (QML) 更适合移动端 UI但 Widgets 项目更能验证基础 C 和构建系统的正确性。将项目命名为HelloAndroid选择合适路径。在 “Kit Selection” 页面这次要同时勾选桌面套件和你刚刚看到的 Android 套件。例如勾选Desktop Qt 6.10.1 MSVC2022 64bit和Android Qt 6.10.1 Clang arm64-v8a。这样一个项目就可以同时编译桌面版和 Android 版。完成项目创建。5.2 项目结构解析创建完成后在项目目录中你会发现一些与 Android 相关的特殊文件android/目录这是 Android 项目的核心目录。android/AndroidManifest.xmlAndroid 应用的配置文件定义了应用名称、图标、权限、启动 Activity 等。android/build.gradleGradle 构建脚本定义了依赖、签名、构建变体等。android/res/存放应用图标、字符串等资源。android/gradle/和android/gradle.propertiesGradle 包装器和配置文件。android/目录下的文件通常不需要手动修改Qt Creator 和androiddeployqt工具会管理它们。但了解其存在很重要。5.3 修改 Android 清单文件可选但推荐默认的AndroidManifest.xml可能使用最低的 API 级别。为了兼容性和使用新特性我们最好调整一下。在 Qt Creator 的项目文件树中打开android/AndroidManifest.xml。找到uses-sdk android:minSdkVersion”...” android:targetSdkVersion”...” /这一行。建议将minSdkVersion设置为21(Android 5.0)targetSdkVersion设置为34(Android 14) 或与你下载的 SDK Platform 版本一致。这确保了应用能运行在大多数设备上并能面向较新的系统进行优化。!-- 文件路径: android/AndroidManifest.xml -- ?xml version”1.0” encoding”UTF-8”? manifest xmlns:android”http://schemas.android.com/apk/res/android” package”org.qtproject.example.HelloAndroid” android:versionCode”1” android:versionName”1.0” uses-sdk android:minSdkVersion”21” android:targetSdkVersion”34” / !-- ... 其他内容保持不变 ... -- /manifest保存文件。6. 构建与部署到 Android 设备激动人心的时刻到了我们将把应用运行起来。6.1 选择构建套件与模式在 Qt Creator 左下角你会看到套件选择器和构建模式选择器。确保在套件选择器中选择了你的 Android 套件如Android Qt 6.10.1 Clang arm64-v8a。构建模式通常选择Release以获得更小的 APK初次调试也可以选Debug。6.2 连接 Android 设备你有两种选择物理真机或虚拟设备 (AVD)。对于物理真机用 USB 数据线连接手机和电脑。在手机上开启 “开发者选项” 和 “USB 调试” 模式通常在 “设置” - “关于手机” - 多次点击 “版本号” 开启开发者选项然后在 “系统” 或 “开发者选项” 中找到 “USB 调试”。在电脑命令行运行adb devices应该能看到你的设备序列号并显示device。如果显示unauthorized需要在手机上弹出的授权对话框中点击确认。对于虚拟设备 (AVD)在 Android Studio 中打开 “AVD Manager” (可以通过 “More Actions” - “AVD Manager” 进入)。点击 “Create Virtual Device”选择一个设备型号如 Pixel 5然后选择你之前下载的 Android 系统镜像如 R API 30。创建完成后点击绿色的启动按钮。等待模拟器启动完毕。同样在命令行运行adb devices应该能看到一个emulator-xxxx的设备。6.3 编译并运行在 Qt Creator 中点击左下角的绿色三角运行按钮或按CtrlR。Qt Creator 会开始构建项目。这个过程会执行以下步骤编译你的 C 代码和 Qt 库为 Android 架构的.so文件。调用androiddeployqt工具生成 Android Studio 项目结构。使用gradle将原生库、Java 存根、资源文件打包成 APK。通过adb将 APK 安装到已连接的设备真机或模拟器。在设备上启动应用。如果一切顺利你将在你的 Android 设备上看到一个带有简单按钮的 Qt 窗口这意味着你的 Qt 应用已经成功在 Android 系统上运行。7. 常见问题与深度排查指南即使按照步骤操作也可能会遇到问题。下面是一些最常见的问题及其解决方案。7.1 构建阶段失败问题现象可能原因排查与解决思路错误NDK 未找到或版本不兼容1. NDK 路径在 Qt Creator 中配置错误。2. 安装的 NDK 版本不被 Qt 6.10.1 支持。1. 检查 “选项” - “设备” - “Android” 中的 NDK 路径确保指向ndk/[version]目录。2. Qt 6.10.1 官方推荐 NDK r25c。请安装此版本。可在%ANDROID_SDK_ROOT%/ndk下查看已安装版本。错误无法找到android命令或gradle1. Android SDK 路径错误。2. 命令行工具未安装。3. 系统环境变量PATH未包含 SDK 的tools和platform-tools。1. 确认 Qt Creator 中 SDK 路径正确。2. 在 Android Studio 的 SDK Manager 中确保安装了 “Android SDK Command-line Tools”。3. 将[SDK路径]\tools和[SDK路径]\platform-tools添加到系统的PATH环境变量中并重启 Qt Creator。错误Java 版本问题1. JDK 路径错误。2. 使用了过新或过旧的 JDK 版本。1. 确认 Qt Creator 中 JDK 路径指向有效的 JDK 根目录包含bin,lib等文件夹。2. Qt 6.10.1 通常兼容 JDK 11 和 17。建议使用 OpenJDK 17。错误androiddeployqt执行失败1. Android 构建工具版本过高或过低。2. 项目android/目录下的 Gradle 文件配置冲突。1. 尝试在 Android Studio 的 SDK Manager 中安装一个稍旧但稳定的 Build-Tools 版本如 33.0.0。2. 清理项目“构建” - “清理项目”删除项目目录下的build-*文件夹和android/build文件夹然后重新构建。7.2 部署与运行阶段失败问题现象可能原因排查与解决思路设备未找到 (No devices found)1. 设备未连接或未授权。2.adb未正确运行或存在多个adb进程冲突。1. 检查 USB 连接和手机上的调试授权。在命令行运行adb devices确认设备列表。2. 结束所有可能的adb进程adb kill-server然后重启 (adb start-server)。确保 Qt Creator 和 Android Studio 没有同时占用adb。应用安装失败1. 设备上已存在同名应用但签名不同。2. 设备存储空间不足。3. APK 与设备 CPU 架构不兼容。1. 卸载设备上已有的同名应用。2. 检查设备存储。3. 在 Qt Creator 的 Android 套件设置中确保选择了设备支持的 ABI如arm64-v8a。现代手机大多支持此架构。应用启动后立即崩溃1. 缺少必要的 Qt 原生库 (*.so)。2.AndroidManifest.xml中权限或配置错误。3. C 代码中存在平台相关的未定义行为。1. 这是最复杂的情况。首先查看adb logcat输出获取崩溃日志。在命令行运行 adb logcat7.3 获取并分析日志日志是排查 Android 应用问题的生命线。使用命令行打开终端连接设备后使用adb logcat命令可以查看实时日志。为了过滤 Qt 相关日志可以使用adb logcat | grep -i “qt”或者查看所有致命错误adb logcat *:E使用 Qt Creator当通过 Qt Creator 部署应用时下方的 “应用程序输出” 或 “编译输出” 面板通常会显示adb logcat的输出。如果应用崩溃关键的错误堆栈信息会在这里显示。分析日志重点关注FATAL EXCEPTION、signal(如 SIGSEGV 段错误)、Unable to load library等关键字。将错误信息复制到搜索引擎中通常能找到解决方案。8. 最佳实践与进阶配置建议成功运行第一个应用后以下建议能帮助你在实际项目中走得更稳。8.1 项目管理与配置.pro文件配置在项目根目录的.pro文件中可以针对 Android 进行条件编译。# 示例为 Android 平台添加特定的预处理器定义和库 android { DEFINES ANDROID # 添加 Android 特定的依赖如传感器、定位 # QT androidextras } else:win32 { DEFINES WINDOWS }管理依赖库如果你的项目依赖第三方 C 库需要为其编译 Android 版本使用 NDK 工具链并将对应的.so文件和头文件放入项目并在.pro文件中通过ANDROID_EXTRA_LIBS变量引入。图标与名称在android/res目录下替换不同分辨率的drawable图片来更改应用图标。在android/AndroidManifest.xml中修改android:label属性来更改应用显示名称。8.2 性能与兼容性选择正确的 ABI在 Qt Creator 的 Android 套件设置中你可以选择生成哪些 CPU 架构的库。为了减小 APK 体积可以只选择arm64-v8a覆盖绝大多数现代设备。如果需要兼容老设备可以加上armeabi-v7a。避免选择x86和x86_64除非你明确需要为 Intel 处理器的 Android 设备或模拟器分发应用。启用 QML 缓存如果使用 Qt Quick (QML)在main.cpp中启用 QML 缓存可以提升启动速度。#ifdef Q_OS_ANDROID QQuickStyle::setStyle(“Material”); // 设置 Android 风格 // 启用 QML 磁盘缓存Qt 6.7 // QQmlApplicationEngine::setPersistentDiskCacheEnabled(true); #endif权限管理在AndroidManifest.xml中按需添加权限如网络、定位、存储等。遵循最小权限原则。8.3 调试技巧使用qDebug()输出在代码中大量使用qDebug() “message”;这些输出在 Android 上会重定向到adb logcat是追踪程序流的最简单方法。配置调试符号在 Release 构建中为了减小体积调试符号会被剥离。如果需要分析 Release 版本的崩溃可以在.pro文件中为 Android 配置分离的调试信息或使用android:debuggable”true”仅用于测试。桌面先行尽可能多地在桌面套件下进行开发和调试因为桌面环境的构建和调试循环要快得多。将平台相关的代码用#ifdef Q_OS_ANDROID隔离。8.4 发布准备应用签名在 Qt Creator 中你可以配置一个调试密钥库默认用于开发。发布到应用商店前必须使用正式的发布密钥对 APK 进行签名。可以在 “项目” - “构建步骤” - “构建 Android APK” 中配置签名信息。优化 APK 大小检查生成的 APK移除未使用的 Qt 模块在.pro文件中QT -压缩资源文件并考虑使用 Android App Bundle (aab) 格式进行分发Google Play 支持此格式并能针对不同设备生成优化后的 APK。测试矩阵在多种不同品牌、型号、系统版本的 Android 真机上进行测试确保 UI 适配和功能正常。虚拟设备也是一个很好的补充。通过以上步骤你应该已经成功搭建了 Qt 6.10.1 的 Android 开发环境并理解了从编译到部署的完整流程。记住环境配置是一次性的投入一旦打通后续的开发工作就会顺畅许多。如果在实践中遇到本教程未覆盖的特定问题善用日志 (adb logcat) 和搜索引擎Qt 社区和官方文档也是强大的后盾。