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