Qt 实战：从零开始，使用 Qt 进行安卓开发

摘要：本文系统讲解 Qt 安卓开发全流程，从环境搭建、项目创建、平台配置，到真机调试、APK 打包，全程搭配可直接编译运行的极简示例，解决新手无实例、上手难的问题。同时汇总开发常见坑点，帮助 C++/Qt 开发者快速实现跨平台安卓应用开发。适用人群：Qt 初学者、有 C++ 基础想入门安卓开发的开发者、需要跨平台移动端解决方案的工程师开发环境：Windows 11、Qt 5.15 LTS、安卓真机

前言

在跨平台开发领域，Qt 凭借「一次编写，多平台编译运行」的优势，成为 C++ 开发者开发安卓应用的优选方案。无需深入学习 Java/Kotlin，即可复用桌面端业务逻辑，大幅降低开发与维护成本。

本文摒弃纯理论讲解，全程搭配完整可运行的极简示例，从环境配置到最终打包，带你完整走通开发流程，新手也能快速上手。

一、开发环境必备配置

1. Qt 安装与组件选择

1. 访问 Qt 官方下载页，下载Qt Online Installer，注册免费 Qt 账号后进行安装。
2. 关键组件勾选（核心步骤，不可遗漏）：
   • 开发工具：Qt Creator、MinGW 编译工具。
   • 安卓核心组件：勾选对应 Qt 版本的Android ARMv7、Android ARM64-v8a（适配主流安卓手机），模拟器调试可额外勾选Android x86、Android x86_64。
   • 必选工具：Android Settings相关配置组件。
3. 安装路径禁止包含中文、空格和特殊字符，防止后续编译、打包出现未知错误。

2. 安卓依赖环境配置

Qt 安卓开发依赖JDK、Android SDK、Android NDK，推荐新手使用自动配置方式。

1. 打开 Qt Creator，进入工具 → 选项 → 设备 → Android。
2. 界面会提示缺失依赖，点击打开 SDK 管理工具，按照向导指引，Qt 会自动下载并配置兼容版本的 JDK、SDK、NDK。
3. 配置完成后，路径会自动填充，点击「应用 → 确定」。
4. 验证环境：进入工具 → 选项 → 构建和运行 → 套件，若 Android 相关套件显示为绿色对勾，说明环境配置成功；红色标识则根据提示修复缺失依赖。

二、创建安卓项目并编写极简示例

本节直接创建项目，并编写按钮点击更新文本的极简示例，代码无平台兼容问题，可直接在桌面端调试后，编译运行到安卓设备。

1. 创建基础项目

1. Qt Creator 中点击文件 → 新建文件或项目 → 应用程序 → Qt Widgets Application，点击「选择」。
2. 设置项目名称（如QtAndroidSimpleDemo），选择项目路径，路径和名称均不能有中文。
3. 构建系统选择qmake（新手兼容性最优），类信息保持默认。
4. 关键步骤：在「构建套件选择」页面，同时勾选桌面套件与 Android 套件，方便先在桌面调试逻辑，再移植到安卓。
5. 完成项目创建，得到默认的项目文件结构。

2. 项目配置文件（.pro）修改

打开项目的.pro文件，替换为以下完整配置，包含安卓版本、权限、文件清单等关键配置，直接复制使用。

qmake

QT += core gui greaterThan(QT_MAJOR_VERSION, 4): QT += widgets # 安卓平台核心配置 ANDROID_MIN_SDK_VERSION = 21 ANDROID_TARGET_SDK_VERSION = 33 ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android # 按需添加安卓权限，本示例仅需基础权限，如需网络、存储再额外添加 ANDROID_PERMISSIONS += android.permission.INTERNET # 项目基础配置 TARGET = QtAndroidSimpleDemo TEMPLATE = app # 源码文件 SOURCES += \ main.cpp \ mainwindow.cpp HEADERS += \ mainwindow.h FORMS += \ mainwindow.ui

3. 头文件 mainwindow.h

该文件定义窗口、按钮、标签以及点击槽函数，直接复制替换原有代码。

cpp

运行

#ifndef MAINWINDOW_H #define MAINWINDOW_H #include <QMainWindow> #include <QPushButton> #include <QLabel> QT_BEGIN_NAMESPACE namespace Ui { class MainWindow; } QT_END_NAMESPACE class MainWindow : public QMainWindow { Q_OBJECT public: MainWindow(QWidget *parent = nullptr); ~MainWindow(); private slots: // 按钮点击响应的槽函数 void onTestButtonClicked(); private: Ui::MainWindow *ui; // 声明按钮和文本标签 QPushButton *testButton; QLabel *showLabel; }; #endif // MAINWINDOW_H

4. 源文件 mainwindow.cpp

实现窗口初始化、控件布局、按钮点击逻辑，是示例的核心功能代码。

cpp

运行

#include "mainwindow.h" #include "ui_mainwindow.h" MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) { ui->setupUi(this); // 设置窗口标题 this->setWindowTitle("Qt安卓极简示例"); // 初始化按钮 testButton = new QPushButton("点击我", this); // 设置按钮位置与大小，适配移动端触控 testButton->setGeometry(100, 200, 200, 80); // 初始化标签 showLabel = new QLabel("等待点击...", this); showLabel->setGeometry(100, 300, 200, 60); // 标签文字居中 showLabel->setAlignment(Qt::AlignCenter); // 信号与槽连接，按钮点击触发槽函数 connect(testButton, &QPushButton::clicked, this, &MainWindow::onTestButtonClicked); } MainWindow::~MainWindow() { delete ui; } // 槽函数实现：点击按钮后修改标签显示内容 void MainWindow::onTestButtonClicked() { showLabel->setText("Qt安卓开发示例运行成功！"); }

5. 主函数 main.cpp

程序入口，无需修改，保持默认即可，确保应用正常启动。

cpp

运行

#include "mainwindow.h" #include <QApplication> int main(int argc, char *argv[]) { QApplication a(argc, argv); MainWindow w; // 桌面端调试窗口大小，安卓端会自动适配全屏 w.resize(400, 600); w.show(); return a.exec(); }

三、真机调试与运行

1. 安卓设备开启调试模式

1. 打开手机设置 → 关于手机，连续点击「版本号」，直至提示「已开启开发者选项」。
2. 返回设置，进入「开发者选项」，开启USB 调试。
3. 使用原装 USB 数据线连接电脑与手机，手机端弹出的调试授权弹窗，选择允许。

2. 编译并运行到安卓设备

1. 在 Qt Creator左下角，将构建套件切换为Android 对应套件。
2. 点击左侧工具栏的构建按钮，首次编译会下载依赖库，耗时较长，耐心等待。
3. 构建完成无报错后，点击运行按钮。
4. Qt 会自动将应用打包、安装到安卓设备并启动。点击界面中的按钮，标签文字发生变化，说明示例运行成功。

调试小贴士：代码中添加断点，点击「调试」按钮，可像桌面端一样单步调试、查看变量，快速定位问题。

四、APK 签名打包与发布

1. 创建安卓签名文件

安卓应用上架应用商店，必须进行签名，且签名文件需永久保存。

1. 进入工具 → 选项 → 设备 → Android → 签名。
2. 点击「创建」，填写：密钥库路径、密钥库密码、密钥别名、别名密码、证书信息、有效期。
3. 点击完成，生成.keystore签名文件，务必妥善保管，丢失后无法更新应用。

2. 打包 Release 版 APK

1. 在 Qt Creator 左下角，将构建模式从Debug 切换为 Release，提升应用性能，减小安装包体积。

• 点击构建 → 构建项目 "QtAndroidSimpleDemo"，完成 Release 版本编译。

1. 点击构建 → 部署项目，选择已创建的签名文件，输入对应密码。
2. 打包完成后，在项目构建目录的android-build/build/outputs/apk/路径下，找到签名后的 APK，可直接分发或上架应用商店。

五、常见问题与解决方案

1. NDK 版本不兼容，编译报错解决方案：Qt 5.15 推荐搭配NDK r21e，Qt 6.x 参考官方适配的 NDK 版本。在 Qt Creator 的 Android 配置页面，更换为兼容版本的 NDK，重新配置路径。
2. 电脑无法识别安卓设备解决方案：更换原装数据线；检查 USB 调试是否开启；Windows 系统在设备管理器中安装手机对应 USB 驱动；重启手机和 Qt Creator。
3. 应用安装后闪退解决方案：检查代码中是否使用了 Windows/Mac 专属 API；核对AndroidManifest.xml中权限是否配置完整；通过 Qt Creator 的「应用输出」窗口，查看崩溃日志，定位问题代码。
4. APK 安装包体积过大解决方案：使用 Release 模式编译；在.pro文件中移除未使用的 Qt 模块；压缩图片、音频等资源文件；删除未使用的源码和配置文件。

六、总结与进阶方向

本文通过完整的极简示例，完整覆盖了 Qt 安卓开发从环境搭建、代码编写、真机调试到打包发布的全流程。该示例无平台兼容问题，可作为你后续复杂项目的基础模板。

进阶学习方向：

1. 学习 Qt Quick，开发更贴合移动端设计规范的现代化 UI。
2. 通过JNI 接口，调用安卓原生 API，实现推送、支付、相机等原生功能。
3. 适配全面屏、折叠屏、平板，优化横竖屏切换、多分辨率适配。
4. 切换为 CMake 构建系统，适配 Qt 6 版本的安卓开发。