在桌面端、移動端乃至嵌入式領域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 適配以及性能優化技巧。 Qt 6.10.1 Android開發環境配置全攻略：從零搭建到真機調試
在桌面端、移動端乃至嵌入式領域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 適配以及性能優化技巧。