Qt 6 嵌入 Android 原生应用完整教程

【实战】Qt 6 嵌入 Android 原生应用完整教程（附可运行Demo）

前言

在跨平台开发场景中，Qt 凭借其出色的界面绘制能力和跨平台兼容性广受开发者青睐，但有时我们需要将 Qt 界面嵌入到 Android 原生应用中，实现「原生性能 + Qt 灵活界面」的双重优势。本文将详细讲解 Qt 6 与 Android 原生应用的无缝集成方案，提供完整的可运行 Demo，从环境搭建到编译部署一步到位，帮助开发者快速落地该技术方案。

一、项目概述

1. 功能亮点

✅ Qt 界面无缝嵌入 Android 原生应用，无明显切换感

✅ 保留 Android 原生性能，同时享受 Qt 跨平台界面开发效率

✅ 仅支持 ARM64 架构（arm64-v8a），适配主流安卓设备

✅ 支持 Qt 与 Android 组件混合开发，可相互调用扩展功能

✅ 提供完整可复用 Demo，直接修改即可适配自有项目

2. 核心技术栈

• 跨平台框架：Qt 6.x（专为 Android 编译版本）
• 原生开发：Android SDK / NDK
• 构建工具：CMake + Gradle
• 运行环境：JDK 8 及以上版本

二、前置准备（环境搭建）

在开始项目操作前，必须完成以下环境配置，否则会出现编译失败、路径找不到等问题。

1. 必备软件安装

软件/工具	推荐版本	安装说明
Android Studio	最新稳定版	用于创建、编辑和运行 Android 原生项目，后续可通过其安装 SDK/NDK
Qt for Android	Qt 6.5+（推荐 6.10）	需在 Qt Installer 中勾选「Android ARM64-v8a」组件，同时安装对应桌面版本（mingw_64/msvc） 🔗 配套安装教程： ① 官方权威教程（英文）：Qt for Android 安装配置官方指南 ② 优质中文实战教程：Qt 6 安装 Android 组件详细步骤（含避坑）
NDK	25+（推荐 28.2.x）	通过 Android Studio 的 SDK Manager 安装，与 Qt 6 兼容
CMake	3.22+	可通过 Android Studio 或 Qt 配套工具安装，需配置环境变量
JDK	8 / 11	Android Studio 自带 JDK，也可手动安装独立 JDK，确保 JAVA_HOME 配置正确

2. 关键环境配置说明

• 安装 Qt 时，务必同时安装「Android 编译组件」和「对应桌面版本」（后续 CMake 配置需要用到桌面 Qt 作为宿主路径）
• 所有工具安装路径尽量避免中文和空格，否则容易出现路径解析错误
• 配置环境变量：将 Qt 的 bin 目录、CMake 的 bin 目录添加到系统 PATH 中

三、快速开始（直接运行Demo）

如果您想快速验证效果，可直接按照以下步骤运行已准备好的 Demo 项目，无需先修改代码。

步骤 1：获取项目源码

项目完整结构已打包，目录结构如下（后续修改代码需重点关注这些目录）：

QtAndroidDemo/
├── qt_lib/                    # Qt C++ 库源码（核心界面逻辑）
│   ├── CMakeLists.txt         # Qt 库 CMake 构建配置
│   └── *.cpp/*.h              # Qt 界面、业务逻辑源代码
├── android_app/              # Android 宿主应用（原生容器）
│   ├── app/
│   │   ├── src/main/
│   │   │   ├── java/         # Android 原生 Java 源码
│   │   │   ├── jniLibs/      # 预编译 Qt .so 库（arm64-v8a）
│   │   │   ├── assets/       # Qt 资源文件（图片、配置等）
│   │   │   └── AndroidManifest.xml  # Android 清单配置
│   │   ├── libs/             # Qt Android 核心 JAR 依赖包
│   │   └── build.gradle      # Android 项目 Gradle 构建配置
│   └── local.properties      # SDK/NDK/Qt 路径配置文件
├── QtLoader.bytecode         # Qt 加载器字节码（辅助 Qt 初始化）
└── README.md                 # 项目本地说明文档

步骤 2：打开并配置 Android 项目

1. 启动 Android Studio，点击「Open」按钮
2. 导航到 Demo 目录下的 QtAndroidDemo\android_app，选择该目录并打开
3. 等待 Gradle Sync 自动完成（首次打开可能需要下载依赖，耐心等待）
4. 若出现「SDK/NDK 路径缺失」提示，打开 local.properties，补充以下配置（根据本地安装路径修改）：

sdk.dir=D:\\Android\\SDK
ndk.dir=D:\\Android\\SDK\\ndk\\28.2.13676358
qt.dir=D:\\Software\\QT\\6.10.1\\android_arm64_v8a

步骤 3：运行项目

1. 准备测试设备：连接开启「USB 调试」的安卓真机（推荐，兼容性更好），或启动 ARM64 架构的安卓模拟器
2. 在 Android Studio 顶部工具栏选择目标设备
3. 点击绿色三角形「Run」按钮，等待项目编译、安装和运行
4. 成功运行后，即可在设备上看到 Qt 界面嵌入在 Android 原生应用中的效果

四、核心操作：重新编译 Qt 库（修改Qt代码后必做）

当您修改了 qt_lib 目录下的 Qt 代码（界面、业务逻辑等）后，需要重新编译 Qt 库，并将编译产物部署到 Android 项目中，否则修改不会生效。以下以 Windows 环境（PowerShell） 为例，提供完整编译步骤。

步骤 1：进入 Qt 库源码目录

打开 Windows PowerShell（Win + S 搜索「PowerShell」），通过 cd 命令进入 qt_lib 目录，例如：

cd D:\\Projects\\QtAndroidDemo\\qt_lib

步骤 2：执行完整编译与部署脚本

直接复制以下脚本运行（重点：根据本地实际路径修改环境变量配置），脚本已包含「清理旧构建 → 环境配置 → CMake 配置 → 编译 → 部署」全流程：

# 1. 清理旧构建产物（避免缓存导致编译异常）
if (Test-Path build) { Remove-Item -Recurse -Force build }

# 2. 配置环境变量（务必根据本地实际路径修改！）
$env:ANDROID_SDK_ROOT = "D:\Android\SDK"
$env:ANDROID_NDK_ROOT = "D:\Android\SDK\ndk\28.2.13676358"
$env:PATH = "D:\Android\SDK\cmake\3.22.1\bin;" + $env:PATH  # 将 CMake 添加到临时 PATH

# 3. 运行 qt-cmake 进行项目配置（Qt 专属 CMake 封装）
# 注意：-DQT_HOST_PATH 必须指向同版本 Qt 桌面构建（mingw_64 或 msvc，不可省略）
& "D:\Software\QT\6.10.1\android_arm64_v8a\bin\qt-cmake.bat" -S . -B build -GNinja `
    -DANDROID_ABI=arm64-v8a `  # 指定架构为 ARM64-v8a
    -DQT_HOST_PATH="D:\Software\QT\6.10.1\mingw_64"

# 4. 开始编译 Qt 库（使用 Ninja 构建，速度更快）
cmake --build build

# 5. 部署编译好的 .so 库到 Android 项目（覆盖旧文件）
Copy-Item "build\libQtAndroidLib.so" "..\android_app\app\src\main\jniLibs\arm64-v8a\" -Force

步骤 3：验证编译结果

部署完成后，回到 Android Studio，点击「Run」按钮重新运行项目，即可看到 Qt 代码修改后的效果。

五、注意事项（避坑指南）

1. 架构兼容性：当前 Demo 仅支持 ARM64 架构（arm64-v8a），不支持 x86、armeabi-v7a 架构，需确保测试设备/模拟器为 ARM64 架构，否则会出现「安装失败」或「闪退」
2. 路径问题：所有配置路径（Qt、SDK、NDK）务必避免中文和空格，这是 Android 与 Qt 编译的常见坑，出现「文件找不到」优先检查路径
3. Qt 环境配置 ：编译 Qt 库时，必须确保 qt-cmake.bat 路径正确，且 QT_HOST_PATH 指向同版本桌面 Qt，否则会出现「跨平台构建不支持」错误
4. Gradle 同步问题：Android 项目打开后若 Gradle 同步失败，可尝试「File → Invalidate Caches → 勾选 All Caches → Restart」清理缓存后重新同步
5. 权限配置 ：若 Qt 界面需要访问手机存储、相机等权限，需在 AndroidManifest.xml 中添加对应权限声明，否则会出现功能异常
6. 版本兼容性：Qt 6 与 Android NDK 存在版本兼容关系，建议使用 Qt 6.8+ 搭配 NDK 25+，避免出现编译报错（具体兼容列表可参考 Qt 官方文档）

六、扩展与优化（进阶方向）

1. 多架构支持 ：若需要支持 armeabi-v7a 架构，可修改 CMake 配置中的 ANDROID_ABI 为 armeabi-v7a，并重新编译 Qt 库，同时在 Android 项目的 build.gradle 中添加对应架构配置
2. Qt 与 Android 相互调用：可通过 JNI 实现 Qt 调用 Android 原生方法（如调用相机、支付），或 Android 原生调用 Qt 接口（如传递参数、触发界面刷新）
3. 资源优化：压缩 Qt 资源文件（图片、字体），减少 .so 库体积，提升应用启动速度
4. 混淆配置：发布正式版应用时，需在 Android 项目中配置 ProGuard 混淆规则，保护核心代码，同时避免混淆 Qt 相关类导致闪退

七、参考资料

1. Qt 官方 Android 开发文档：https://doc.qt.io/qt-6/android.html
2. Qt 官方 Android 快速入门：https://doc.qt.io/qt-6/android-getting-started.html
3. Android NDK 官方文档：https://developer.android.com/ndk
4. CMake 跨平台构建指南：https://cmake.org/cmake/help/latest/

总结

本文提供了一套完整的 Qt 6 嵌入 Android 原生应用的实战方案，从环境搭建、快速运行 Demo 到重新编译 Qt 库，步骤清晰可落地。通过该方案，开发者可以兼顾 Android 原生性能和 Qt 跨平台开发效率，满足复杂场景下的开发需求。

项目 Demo 地址：Qt 6 嵌入 Android 原生应用可运行 Demo

✨ 说明：

1. Demo 已预编译 arm64-v8a 架构 .so 库，下载后可直接按照本文「快速开始」步骤运行
2. 包含完整项目结构、编译脚本和配置文件，无需额外补充依赖
3. 建议下载后先备份原始文件，再进行二次修改和扩展