Qt for Android开发环境搭建与配置指南-代码聚汇网

Qt for Android开发环境搭建与配置指南

张瑞15129378030·2026-07-23·阅读 40 GEO检测（免费）

Qt for Android跨平台开发Android SDK

|难度：普通|阅读约 16 分钟

1. 为什么需要搭建Qt for Android开发环境？

移动应用开发已经成为当今软件开发的重要领域，而Qt框架因其跨平台特性，让开发者能够使用同一套代码同时部署到Android、iOS和桌面平台。我最初接触Qt for Android是在2018年，当时公司需要将一个工业控制软件移植到平板设备上。经过多次实践，我总结出一套稳定的环境搭建方法，可以同时支持Qt5和Qt6版本。

Qt for Android开发环境的核心组件包括：

Qt Creator（建议使用最新版）
Android SDK（API级别至少21以上）
Android NDK（版本需要与Qt版本匹配）
Java JDK（特定版本要求）
Qt for Android套件

重要提示：不同版本的Qt对Android工具链的要求差异很大，Qt5和Qt6的配置方式也有显著区别。本文将分别说明两者的配置要点。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 基础环境准备

2.1 安装Java开发工具包(JDK)

Qt for Android需要Java环境支持，但版本选择很关键：

Qt5通常需要JDK 8（1.8版本）
Qt6则需要JDK 11或更高版本

我推荐使用OpenJDK而不是Oracle JDK，因为前者没有商业使用限制。在Ubuntu系统上可以这样安装：

bash复制sudo apt install openjdk-11-jdk

安装后验证版本：

bash复制java -version
javac -version

2.2 安装Android Studio

虽然我们主要使用Qt Creator进行开发，但仍需要Android Studio来获取必要的SDK组件。从官网下载后，安装时注意：

自定义安装路径，避免使用包含空格或特殊字符的路径
安装时勾选"Android SDK"和"Android SDK Platform"
确保安装Android SDK Build-Tools

安装完成后，打开Android Studio的SDK Manager：

安装至少一个Android平台（如API 31）
安装NDK（Side by side）版本
安装CMake和LLDB工具

2.3 配置Android环境变量

将以下路径添加到系统环境变量中（根据实际安装路径调整）：

bash复制export ANDROID_HOME=/path/to/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/ndk/21.3.6528147  # NDK版本号需对应

3. Qt安装与配置

3.1 安装Qt主程序

从Qt官网下载在线安装器，注意选择正确的版本：

Qt5长期支持版本（如5.15.2）
Qt6最新稳定版（如6.5.0）

安装时务必勾选：

Qt Creator
对应Android套件（如Qt 6.5.0 for Android ARM64-v8a）
Additional Libraries（如Qt Multimedia等）

3.2 配置Qt Creator中的Android工具链

打开Qt Creator，进入"工具→选项→设备→Android"：

设置JDK路径（如/usr/lib/jvm/java-11-openjdk-amd64）
设置Android SDK路径（如/home/user/Android/Sdk）
设置Android NDK路径（如/home/user/Android/Sdk/ndk/21.3.6528147）
设置SDK Manager和AVD Manager路径

常见问题：如果Qt Creator无法识别NDK，通常是因为版本不匹配。Qt5.15需要NDK r21e，而Qt6需要更新的NDK版本。

4. 创建并配置Qt Android项目

4.1 新建项目注意事项

创建新项目时：

选择"Mobile Application"模板
在"Build System"选择qmake（Qt5）或CMake（Qt6）
确保Kit选择中包含Android套件

4.2 Android清单文件配置

Qt Creator会自动生成AndroidManifest.xml，但有几个关键参数需要检查：

xml复制<uses-sdk android:minSdkVersion="21" android:targetSdkVersion="31"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-feature android:glEsVersion="0x00030000" android:required="true"/>

对于需要文件访问的应用，还需添加存储权限：

xml复制<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

4.3 处理Qt5无法拖拽文件的问题

这是Qt5在Android上的常见问题，解决方案是在MainActivity.java中添加：

java复制import android.view.View;
import android.view.ViewGroup;
import org.qtproject.qt5.android.bindings.QtActivity;

public class MainActivity extends QtActivity {
    @Override
    public void setContentView(View view) {
        super.setContentView(view);
        fixDragAndDrop((ViewGroup)view);
    }
    
    private void fixDragAndDrop(ViewGroup viewGroup) {
        final int count = viewGroup.getChildCount();
        for (int i = 0; i < count; i++) {
            View child = viewGroup.getChildAt(i);
            if (child instanceof ViewGroup) {
                fixDragAndDrop((ViewGroup)child);
            } else {
                child.setOnDragListener((v, event) -> {
                    v.getParent().requestDisallowInterceptTouchEvent(true);
                    return false;
                });
            }
        }
    }
}

5. 构建与部署

5.1 调试配置要点

在"项目"设置中：

选择正确的构建套件（Android ARMv7或ARM64）
设置正确的Android SDK版本
对于Qt6，确保CMake配置中包含：

cmake复制find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)
qt_standard_project_setup()

5.2 处理常见构建错误

NDK不兼容错误：清理项目并重新运行qmake
资源文件丢失：确保所有资源文件都列在qrc文件中
权限问题：检查AndroidManifest.xml中的权限声明

5.3 部署到设备

连接Android设备后：

启用开发者选项和USB调试
在设备上授权电脑连接
在Qt Creator中选择目标设备
点击运行，首次部署可能需要较长时间

实测技巧：如果部署失败，尝试重启adb服务：
bash复制adb kill-server
adb start-server

6. Qt5与Qt6的差异处理

6.1 模块变化

Qt6中一些模块发生了变化：

QtWebKit被移除，改用QtWebEngine
QtMultimedia有重大重构
QTextCodec类被移到核心模块

对于需要QTextCodec的Qt6项目，需要：

cpp复制#include <QTextCodec>
// 并在CMake中添加
find_package(Qt6 REQUIRED COMPONENTS Core5Compat)

6.2 构建系统差异

Qt5主要使用qmake，而Qt6推荐使用CMake。如果要将Qt5项目迁移到Qt6：

使用qt-cmake转换工具
更新pro文件中的模块引用
处理废弃的API调用

6.3 图形渲染差异

Qt6默认使用RHI（Render Hardware Interface）而不是Qt5的直接OpenGL调用。这可能导致一些图形代码需要重写：

cpp复制// Qt5
QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
f->glClear(GL_COLOR_BUFFER_BIT);

// Qt6
QRhiCommandBuffer *cb = m_swapChain->currentFrameCommandBuffer();
cb->beginPass(m_swapChain->currentFrameRenderTarget(), Qt::black, {1.0f, 0});

7. 高级配置与优化

7.1 多ABI支持

要支持多种CPU架构，在pro文件中添加：

qmake复制android {
    ANDROID_ABIS = armeabi-v7a arm64-v8a x86 x86_64
}

或在CMake中：

cmake复制set(ANDROID_ABI "armeabi-v7a;arm64-v8a;x86;x86_64")

7.2 减小APK体积

使用Android App Bundle（AAB）格式
启用Proguard代码混淆
仅包含必要的Qt模块

在pro文件中：

qmake复制android {
    ANDROID_EXTRA_LIBS = $$[QT_INSTALL_LIBS]/libQt5Core.so
    ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android
    ANDROID_APP_ICON = $$PWD/android/res/drawable/icon.png
}

7.3 处理Android特定功能

访问Android原生API需要通过JNI。Qt提供了QAndroidJniObject类简化这一过程：

cpp复制// 调用Android Toast
QAndroidJniObject toast = QAndroidJniObject::callStaticObjectMethod(
    "android/widget/Toast", "makeText",
    "(Landroid/content/Context;Ljava/lang/CharSequence;I)Landroid/widget/Toast;",
    QtAndroid::androidActivity().object(),
    QAndroidJniObject::fromString("Hello from Qt!").object(),
    jint(1));
toast.callMethod<void>("show");

8. 实际开发中的经验分享

经过多个Qt Android项目的实践，我总结了以下关键经验：

UI适配问题：Android设备屏幕尺寸多样，建议：
- 使用布局管理器而非固定尺寸
- 为不同DPI提供多套图标
- 测试横竖屏切换
性能优化：
- 避免在主线程执行耗时操作
- 使用QQuickItem代替QWidget以获得更好性能
- 启用硬件加速
存储访问：
- Android 10+引入了作用域存储
- 使用QStandardPaths获取标准路径
- 对于媒体文件，使用MediaStore API
调试技巧：
- 使用adb logcat查看日志
- 在Qt Creator中配置Android日志过滤器
- 对于图形问题，启用OpenGL调试输出
发布准备：
- 使用jarsigner和zipalign工具
- 生成签名密钥库
- 测试不同API级别的兼容性

最后，建议定期更新Qt和Android工具链，但要注意版本兼容性。每次大版本更新时，先在测试项目上验证环境配置，再迁移正式项目。