1. 從零到一為什么要在Windows上折騰Qt for Android如果你是一個(gè)長期在Windows平臺(tái)上用Qt做桌面開發(fā)的C程序員最近手頭的項(xiàng)目突然要求你“順便”出個(gè)Android版本或者你單純想把手頭好用的工具軟件搬到手機(jī)上那你大概率會(huì)點(diǎn)開這篇文章。沒錯(cuò)在Windows上配置Qt6的Android開發(fā)環(huán)境聽起來就像讓一個(gè)習(xí)慣開手動(dòng)擋的老司機(jī)去開一輛新能源車——引擎編譯器不一樣燃料SDK得另加連方向盤部署流程都變了手感。但一旦跑通那種“一份代碼多端運(yùn)行”的暢快感絕對(duì)是值得的。我最近就經(jīng)歷了這么一遭。公司有個(gè)內(nèi)部用的數(shù)據(jù)可視化工具原本是Qt Widgets的桌面程序現(xiàn)在領(lǐng)導(dǎo)希望移動(dòng)端的同事也能在平板上查看實(shí)時(shí)儀表盤。重寫一套時(shí)間成本太高。用Qt Quick重做UI然后編譯到Android就成了最經(jīng)濟(jì)的選擇。然而從安裝軟件到最終APK成功安裝到手機(jī)我花了整整兩天時(shí)間踩遍了幾乎所有能踩的坑。網(wǎng)上教程要么過時(shí)針對(duì)Qt5要么語焉不詳缺了關(guān)鍵步驟就卡死。所以我決定把這次完整的“踩坑”與“填坑”之旅記錄下來目標(biāo)就是讓你能在一兩個(gè)小時(shí)內(nèi)走完我兩天的路。這個(gè)過程的核心其實(shí)就是讓Qt Creator這個(gè)“總裝車間”能夠調(diào)用Google Android SDK/NDK這套“安卓專用生產(chǎn)線”把我們用C/QML寫的代碼編譯成Android系統(tǒng)能認(rèn)的.so庫和APK安裝包。在Windows上這涉及到多個(gè)獨(dú)立組件的協(xié)同Java JDK、Android SDK命令行工具、NDK、以及Qt自身對(duì)Android的預(yù)編譯套件。任何一個(gè)環(huán)節(jié)的路徑、版本不匹配都會(huì)導(dǎo)致編譯失敗。接下來我會(huì)手把手帶你走通全流程并附上我遇到的那些令人頭大的錯(cuò)誤及其解決方案。2. 環(huán)境搭建兵馬未動(dòng)糧草先行配置環(huán)境是萬里長征第一步也是坑最多的地方。原則就一個(gè)版本匹配高于一切。Qt6、Android SDK/NDK、JDK之間有著嚴(yán)格的版本依賴關(guān)系隨意安裝最新版大概率會(huì)失敗。2.1 核心組件清單與版本選擇首先我們得搞清楚需要哪些東西以及我實(shí)測可用的版本組合。Qt 6.5.0 (MSVC 2019 64-bit)這是開發(fā)主體。建議通過Qt官方維護(hù)工具Qt Online Installer安裝。在安裝時(shí)務(wù)必勾選以下組件Qt 6.5.0(或更高穩(wěn)定版如6.6)對(duì)于Qt 6.5.0展開后必須勾選MSVC 2019 64-bit。這是用于編譯Windows桌面版本和生成中間產(chǎn)物的。最關(guān)鍵的一步在Qt 6.5.0下找到并勾選Android相關(guān)的套件。通常會(huì)顯示為Android ARM64-v8a、Android x86_64等。至少勾選Android ARM64-v8a這是目前主流手機(jī)的架構(gòu)。Java JDK 17 (LTS)Qt for Android 的構(gòu)建系統(tǒng)需要JDK。注意這里是個(gè)大坑Android官方推薦使用JDK 11或17。但經(jīng)過實(shí)測高版本JDK如21可能導(dǎo)致androiddeployqt工具報(bào)錯(cuò)。最穩(wěn)妥的選擇是JDK 17 LTS。從Oracle或AdoptiumEclipse Temurin官網(wǎng)下載Windows x64安裝包即可。Android SDK 命令行工具 (Command-line Tools)我們不需要完整的Android Studio IDE只需要其命令行構(gòu)建工具。去Android開發(fā)者官網(wǎng)找到“Command line tools only”進(jìn)行下載。下載后是一個(gè)zip包比如commandlinetools-win-9477386_latest.zip。Android NDK (Native Development Kit)這是編譯C代碼到Android的核心。版本必須謹(jǐn)慎選擇Qt 6.5 官方推薦使用 NDKr25或r26。強(qiáng)烈建議使用Qt Maintenance Tool安裝的NDK或者通過Android SDK Manager安裝指定版本避免兼容性問題。2.2 步步為營的安裝與配置流程接下來是具體的安裝和路徑配置請(qǐng)嚴(yán)格按照順序操作。第一步安裝Java JDK 17運(yùn)行安裝程序安裝路徑建議簡單無空格例如C:\Dev\Java\jdk-17。安裝完成后需要設(shè)置系統(tǒng)環(huán)境變量JAVA_HOME設(shè)置為你的JDK安裝路徑如C:\Dev\Java\jdk-17。在Path變量中添加%JAVA_HOME%\bin。 打開命令提示符CMD輸入java -version和javac -version確認(rèn)輸出為17版本。第二步部署Android SDK命令行工具在你希望安裝SDK的目錄例如C:\Dev\Android下解壓下載的commandlinetools-win-...zip。你會(huì)得到一個(gè)cmdline-tools文件夾。進(jìn)入cmdline-tools你應(yīng)該會(huì)看到一個(gè)以版本號(hào)命名的子文件夾如latest。為了符合SDK Manager的預(yù)期路徑我們需要調(diào)整一下結(jié)構(gòu)在C:\Dev\Android下新建一個(gè)cmdline-tools文件夾。將剛才解壓出來的、帶版本號(hào)的文件夾如latest整個(gè)移動(dòng)到新建的C:\Dev\Android\cmdline-tools下。最終路徑應(yīng)類似C:\Dev\Android\cmdline-tools\latest\bin下存在sdkmanager.bat。設(shè)置環(huán)境變量ANDROID_HOME或ANDROID_SDK_ROOT設(shè)置為SDK根目錄即C:\Dev\Android。在Path中添加%ANDROID_SDK_ROOT%\cmdline-tools\latest\bin和%ANDROID_SDK_ROOT%\platform-tools。打開CMD使用sdkmanager安裝必要包。由于網(wǎng)絡(luò)原因建議先設(shè)置鏡像源。在用戶目錄C:\Users\你的用戶名下的.android文件夾中新建或修改repositories.cfg文件添加國內(nèi)鏡像例如使用清華源sdkmanager --sdk_root%ANDROID_SDK_ROOT% --list但更推薦的做法是通過后面的Qt Creator圖形界面來安裝會(huì)更方便。第三步安裝Android NDK如前所述最省心的辦法是通過Qt Creator來安裝。但如果你想手動(dòng)安裝從Android官網(wǎng)或鏡像站下載NDK r25。解壓到%ANDROID_SDK_ROOT%\ndk目錄下或者任何你喜歡的無空格路徑例如C:\Dev\Android\ndk\25.2.9519653。設(shè)置環(huán)境變量ANDROID_NDK_ROOT指向該路徑。第四步在Qt Creator中配置Kits這是將所有組件串聯(lián)起來的關(guān)鍵一步。打開Qt Creator進(jìn)入工具(Tools)-選項(xiàng)(Options)-設(shè)備(Devices)-Android。JDK Location點(diǎn)擊瀏覽定位到你的JDK安裝目錄如C:\Dev\Java\jdk-17。Qt Creator應(yīng)該能自動(dòng)檢測到版本。Android SDK Location點(diǎn)擊瀏覽定位到你的SDK根目錄如C:\Dev\Android。然后點(diǎn)擊右側(cè)的SDK Manager按鈕。在打開的SDK Manager窗口中SDK Platforms勾選你需要的Android API級(jí)別。對(duì)于Qt 6.5選擇Android 12.0 (API 31)或Android 13.0 (API 33)是比較安全的選擇。建議至少選一個(gè)。SDK Tools勾選Android SDK Build-Tools選擇一個(gè)版本如33.0.2、Android SDK Command-line Tools、Android Emulator Hypervisor Driver for AMD Processors如果你是AMD CPU且要用模擬器、Android SDK Platform-Tools必須。最重要的是在這里找到并勾選NDK (Side by side)然后選擇版本例如25.2.9519653。在這里安裝可以確保路徑被Qt Creator自動(dòng)識(shí)別。點(diǎn)擊Apply進(jìn)行安裝。這個(gè)過程可能需要一些時(shí)間取決于網(wǎng)絡(luò)。安裝完成后關(guān)閉SDK Manager回到Android配置頁面。點(diǎn)擊NDK Location右側(cè)的瀏覽如果前面步驟正確這里應(yīng)該已經(jīng)自動(dòng)填充了NDK路徑如C:\Dev\Android\ndk\25.2.9519653。如果沒有請(qǐng)手動(dòng)指定。點(diǎn)擊Apply保存所有配置。關(guān)鍵提示配置完成后務(wù)必重啟Qt Creator以確保所有環(huán)境變量和路徑生效。這是避免許多靈異問題的好習(xí)慣。3. 創(chuàng)建與配置你的第一個(gè)Qt Android項(xiàng)目環(huán)境配好了我們來點(diǎn)實(shí)際的——?jiǎng)?chuàng)建一個(gè)能跑在手機(jī)上的App。3.1 項(xiàng)目創(chuàng)建與套件選擇打開Qt Creator選擇文件(File)-新建項(xiàng)目(New Project)。選擇Application-Qt Quick Application - Empty。給項(xiàng)目起個(gè)名字比如HelloAndroidQt。在選擇構(gòu)建系統(tǒng)這一步對(duì)于新手建議選擇qmake它的配置更直觀。CMake雖然更強(qiáng)大但初期配置稍復(fù)雜。來到最關(guān)鍵的一步Kit Selection。你會(huì)看到可用的套件列表。你應(yīng)該能看到一個(gè)你電腦上的桌面套件例如Desktop Qt 6.5.0 MSVC2019 64bit。同時(shí)你應(yīng)該能看到至少一個(gè)Android套件例如Android Qt 6.5.0 Clang arm64-v8a。務(wù)必同時(shí)勾選你的桌面套件和這個(gè)Android套件。勾選多個(gè)套件意味著Qt Creator會(huì)為這個(gè)項(xiàng)目同時(shí)維護(hù)桌面和Android的構(gòu)建配置。完成創(chuàng)建。3.2 理解并配置項(xiàng)目文件.pro項(xiàng)目創(chuàng)建后我們主要關(guān)注.pro文件如果是qmake項(xiàng)目。默認(rèn)配置可能已經(jīng)可以工作但了解關(guān)鍵配置項(xiàng)很重要。QT quick # 以下是為Android添加的典型配置 android { # 指定Android清單文件通常會(huì)自動(dòng)生成但可以自定義 # ANDROID_PACKAGE_SOURCE_DIR $$PWD/android # 設(shè)置應(yīng)用圖標(biāo)需要將icon.png放在項(xiàng)目根目錄或指定路徑 ANDROID_ICON $$PWD/icon.png # 設(shè)置應(yīng)用名稱在手機(jī)上顯示的名字 ANDROID_APP_NAME My Qt App # 額外的Gradle構(gòu)建屬性解決常見問題 ANDROID_EXTRA_LIBS $$PWD/libs/armeabi-v7a/ # 非常重要的權(quán)限聲明根據(jù)應(yīng)用需要添加 ANDROID_PERMISSIONS \ android.permission.INTERNET \ android.permission.ACCESS_NETWORK_STATE } # 如果你的應(yīng)用需要額外的C庫.so文件 # android: include($$PWD/thirdparty/thirdparty.pri) SOURCES \ main.cpp RESOURCES qml.qrc最重要的其實(shí)是Qt Creator的圖形化配置。在項(xiàng)目模式左側(cè)下選擇項(xiàng)目(Projects)-構(gòu)建(Build)-構(gòu)建步驟(Build Steps)。在Android構(gòu)建配置(Android Build)部分你可以看到Android包名稱(Android package name)它遵循Java包名規(guī)范如org.qtproject.example.HelloAndroidQt這將是你App在系統(tǒng)中的唯一ID。在這里你也可以快速修改應(yīng)用名稱(Application name)、版本(Version)等。3.3 構(gòu)建、部署與真機(jī)調(diào)試切換套件在Qt Creator左下角有一個(gè)套件選擇器。確保從Desktop切換到Android套件如Android Qt 6.5.0 Clang arm64-v8a。連接設(shè)備用USB線連接你的Android手機(jī)。在手機(jī)上開啟開發(fā)者選項(xiàng)和USB調(diào)試。在Qt Creator的設(shè)備(Devices)輸出窗口你應(yīng)該能看到你的設(shè)備被識(shí)別。如果沒識(shí)別嘗試在CMD中運(yùn)行adb devices查看設(shè)備列表并授權(quán)。構(gòu)建與運(yùn)行直接點(diǎn)擊Qt Creator左下角的綠色運(yùn)行按鈕或按CtrlR。Qt Creator會(huì)執(zhí)行以下操作編譯C代碼為ARM架構(gòu)的.so庫。調(diào)用androiddeployqt工具將.so庫、QML文件、資源等打包進(jìn)一個(gè)原生的Android項(xiàng)目框架中。使用Gradle構(gòu)建APK。將APK安裝到已連接的手機(jī)或模擬器。啟動(dòng)應(yīng)用。如果一切順利你將在手機(jī)上看到你的Qt Quick應(yīng)用運(yùn)行起來。第一次構(gòu)建可能會(huì)比較慢因?yàn)镚radle需要下載依賴。4. 疑難雜癥排查手冊(cè)我踩過的那些坑理論上按照上述步驟就能成功。但現(xiàn)實(shí)往往骨感。下面是我遇到并解決的一些典型問題。4.1 構(gòu)建階段常見錯(cuò)誤問題一Cannot find a compatible NDK.或NDK not configured.現(xiàn)象構(gòu)建時(shí)提示找不到NDK或版本不兼容。排查檢查Qt Creator的Android配置工具-選項(xiàng)-設(shè)備-Android確認(rèn)NDK路徑是否正確指向了已安裝的NDK目錄如C:\Dev\Android\ndk\25.2.9519653。確認(rèn)NDK版本。Qt 6.5 官方支持 r25。如果你手動(dòng)下載了其他版本如r23或r27可能會(huì)不兼容。最穩(wěn)妥的方法是使用Qt Creator的SDK Manager安裝Side-by-side NDK。檢查環(huán)境變量ANDROID_NDK_ROOT是否設(shè)置且路徑正確。有時(shí)Qt Creator會(huì)優(yōu)先讀取環(huán)境變量。問題二Failed to find the Build Tools.或Gradle build failed.現(xiàn)象構(gòu)建過程中Gradle報(bào)錯(cuò)提示找不到構(gòu)建工具或下載失敗。排查打開Qt Creator的SDK Manager確認(rèn)已安裝Android SDK Build-Tools的某個(gè)版本如33.0.2。網(wǎng)絡(luò)問題是最常見的元兇。Gradle會(huì)從Google倉庫下載依賴。為Gradle配置國內(nèi)鏡像是必須的。在項(xiàng)目構(gòu)建目錄下或用戶目錄的.gradle文件夾找到或創(chuàng)建init.gradle文件添加阿里云鏡像allprojects { repositories { maven { url https://maven.aliyun.com/repository/public/ } maven { url https://maven.aliyun.com/repository/google/ } maven { url https://maven.aliyun.com/repository/gradle-plugin/ } mavenLocal() google() mavenCentral() } }清理Gradle緩存。關(guān)閉Qt Creator刪除項(xiàng)目目錄下的build-*文件夾和android-build文件夾以及用戶目錄下.gradle/caches和.gradle/wrapper/dists中的相關(guān)文件然后重新構(gòu)建。問題三java.lang.UnsupportedClassVersionError現(xiàn)象構(gòu)建時(shí)出現(xiàn)Java版本不支持的錯(cuò)誤。原因使用的JDK版本過高或過低與Android Gradle插件不兼容。解決統(tǒng)一使用JDK 17 LTS版本。確保Qt Creator中配置的、系統(tǒng)環(huán)境變量指向的、以及命令行中java -version顯示的都是JDK 17。4.2 部署與運(yùn)行階段問題問題四應(yīng)用安裝失敗提示INSTALL_FAILED_UPDATE_INCOMPATIBLE現(xiàn)象APK無法安裝到手機(jī)提示應(yīng)用沖突。原因手機(jī)上已經(jīng)存在一個(gè)包名相同但簽名不同的應(yīng)用可能是你之前調(diào)試安裝的Debug版。解決卸載手機(jī)上的舊版本應(yīng)用再重新安裝。或者在Qt Creator的項(xiàng)目設(shè)置中臨時(shí)修改Android包名稱在后面加個(gè)后綴如.debug2來繞過沖突。問題五應(yīng)用啟動(dòng)后立即閃退Crash現(xiàn)象應(yīng)用安裝成功但一點(diǎn)擊圖標(biāo)就閃退。排查這是最棘手的問題需要查看日志。在Qt Creator的調(diào)試(Debug)輸出窗口或者應(yīng)用程序輸出(Application Output)窗口可能看不到原生C的崩潰信息。必須使用adb logcat命令。打開一個(gè)獨(dú)立的CMD或終端運(yùn)行adb logcat -c # 清空舊日志 adb logcat | findstr qt\|Fatal\|Signal\|DEBUG\|E/ # Windows下過濾關(guān)鍵信息然后再次啟動(dòng)應(yīng)用觀察終端輸出的錯(cuò)誤信息。常見的閃退原因包括缺少權(quán)限在.pro文件中未聲明必要的權(quán)限如網(wǎng)絡(luò)、存儲(chǔ)權(quán)限但在代碼中嘗試訪問。原生庫加載失敗依賴的第三方.so庫未正確打包或架構(gòu)不匹配。確保所有.so庫都放在android/libs/架構(gòu)名/目錄下并在.pro文件中通過ANDROID_EXTRA_LIBS引用。QML模塊未導(dǎo)入在Android上一些Qt Quick控件可能需要額外的模塊。確保在main.cpp中正確注冊(cè)了所有QML類型并且qmldir文件正確。問題六無法連接到本地服務(wù)器或資源加載失敗現(xiàn)象應(yīng)用能運(yùn)行但網(wǎng)絡(luò)請(qǐng)求失敗或本地圖片/QML文件加載不出來。原因Android的網(wǎng)絡(luò)安全策略和文件系統(tǒng)訪問限制。解決網(wǎng)絡(luò)確保已在.pro文件中聲明INTERNET權(quán)限。對(duì)于HTTP明文請(qǐng)求在AndroidManifest.xml中可通過ANDROID_PACKAGE_SOURCE_DIR指定自定義目錄的application標(biāo)簽內(nèi)添加android:usesCleartextTraffictrue僅限調(diào)試上架需用HTTPS。文件在Android上不能使用file://絕對(duì)路徑訪問資源。對(duì)于打包在qrc中的資源使用qrc:/前綴。對(duì)于需要讀寫的用戶數(shù)據(jù)使用QStandardPaths來獲取標(biāo)準(zhǔn)路徑如QStandardPaths::writableLocation(QStandardPaths::AppDataLocation)。4.3 性能與適配優(yōu)化提示UI適配Android設(shè)備尺寸和分辨率碎片化嚴(yán)重。在QML中盡量使用錨點(diǎn)anchors、布局RowLayout,ColumnLayout和相對(duì)單位dp或Qt提供的Screen屬性避免硬編碼像素值。可以使用Qt.platform.os來判斷平臺(tái)進(jìn)行差異化設(shè)計(jì)。啟動(dòng)速度Qt Android應(yīng)用冷啟動(dòng)可能較慢因?yàn)樾枰虞dQt共享庫?？梢钥紤]將關(guān)鍵的首屏UI做得簡單一些或使用啟動(dòng)屏Splash Screen。在AndroidManifest.xml中配置啟動(dòng)主題避免啟動(dòng)時(shí)的白屏/黑屏。庫文件大小Qt的動(dòng)態(tài)庫比較大會(huì)導(dǎo)致APK體積膨脹。發(fā)布時(shí)務(wù)必使用release模式構(gòu)建并考慮使用androiddeployqt的--no-extra-plugins和--no-translations選項(xiàng)來裁剪不必要的插件和翻譯文件。對(duì)于非必要的Qt模塊不要在.pro中用QT 引入。5. 從調(diào)試到發(fā)布生成可上架的APK調(diào)試沒問題后最終我們需要生成一個(gè)可以發(fā)布到應(yīng)用商店的Release版APK。切換到Release模式在Qt Creator左下角的套件選擇器旁邊將構(gòu)建模式從Debug改為Release。生成簽名密鑰發(fā)布APK必須使用簽名密鑰。如果你沒有可以使用JDK的keytool命令生成keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias請(qǐng)妥善保管生成的.jks文件和密碼。在Qt Creator中配置簽名進(jìn)入項(xiàng)目(Projects)-構(gòu)建(Build)-Android構(gòu)建配置(Android Build)。勾選簽署包(Sign package)。點(diǎn)擊創(chuàng)建...來創(chuàng)建一個(gè)新的簽名配置或?yàn)g覽已有的.jks文件。填寫密鑰庫路徑、密碼、別名和別名密碼。構(gòu)建發(fā)布包點(diǎn)擊Qt Creator左下角的錘子圖標(biāo)進(jìn)行構(gòu)建或者直接運(yùn)行會(huì)生成已簽名的APK并安裝到設(shè)備。構(gòu)建完成后在項(xiàng)目的android-build\build\outputs\apk\release目錄下可以找到已簽名的app-release.apk文件這就是可以發(fā)布的最終包。最后的忠告整個(gè)Qt for Android的開發(fā)環(huán)境像一座精密的鐘表任何一個(gè)齒輪組件版本不對(duì)都可能停擺。保持耐心嚴(yán)格按照匹配的版本操作善用adb logcat和搜索引擎搜索錯(cuò)誤信息時(shí)加上“Qt Android”關(guān)鍵詞大部分問題都能找到解決方案。當(dāng)你第一次看到自己寫的Qt程序在手機(jī)上流暢跑起來時(shí)你會(huì)覺得這一切折騰都是值得的。畢竟用C和QML寫跨平臺(tái)UI這種效率和對(duì)硬件的掌控力是其他很多框架難以比擬的。