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