必須安裝獨立的 Qt for Android 套件，桌面版與 Android 版編譯器、庫、工具鏈完全不同。
| 組件 | 版本建議 | 下載來源 | 關鍵配置 |
|---|---|---|---|
| Qt for Android | 與桌面版同大版本（如 5.12.x / 6.2.x） | Qt 官網在線安裝器 → 選 Android armv7/arm64 | 安裝路徑無中文/空格 |
| Android SDK | Command Line Tools 或 Android Studio 內置 | developer.android.com | ANDROID_SDK_ROOT 環境變量 |
| Android NDK | r21e / r23b / r25c（匹配 Qt 版本） | SDK Manager 或 NDK 歷史版本頁 | Qt Creator → Options → Devices → Android → NDK 路徑 |
| Apache Ant | 1.10.x（Qt 5）或 Gradle（Qt 6） | ant.apache.org | 配置 ANT_HOME、Path |
| JDK | JDK 8 (1.8.0_202+) / JDK 11 (Qt 6) | Adoptium / Oracle | JAVA_HOME、Path |
Android ARMv7 (Clang)、Android ARM64 (Clang) 等。Android，Compiler 選上述 ARM 編譯器，Qt Version 選 Android 版 Qt（如 Qt 5.12.12 Android ARMv7）。Build Android APK 步驟存在。#ifdef Q_OS_WIN、第三方 Windows 庫（如 DirectShow、Media Foundation）。QMediaPlayer + 濾鏡器，Android 必須用 QMediaPlayer + MediaPlayer 後端，確保項目 .pro 添加 QT += multimedia，視頻格式以 H.264/AAC MP4 為主。QStandardPaths::writableLocation(QStandardPaths::AppDataLocation) 替代硬編碼 C:/。AndroidManifest.xml 添加 INTERNET、READ_EXTERNAL_STORAGE、WRITE_EXTERNAL_STORAGE（視預覽）。| 錯誤 | 原因 | 解決 |
|---|---|---|
SDK platform not found | SDK 缺少對應 API Level | SDK Manager 安裝 Android SDK Platform 28/29/30 |
NDK toolchain not found | NDK 版本與 Qt 不匹配 | 換 Qt 官方推薦 NDK 版本（文檔有對應表） |
Manifest merger failed | 權限衝突/缺失 | 檢查 AndroidManifest.xml 合併規則 |
java.lang.UnsatisfiedLinkError | so 庫未打包/架構不匹配 | 確認 ANDROID_PACKAGE_SOURCE_DIR、libs/armeabi-v7a/ 下有 .so |
Qt 移植 Android 是系統工程，核心在於完整安裝獨立 Android 工具鏈並在 Qt Creator 正確掛載。建議先跑通官方 examples/multimedia/videoplayer，再遷移自有代碼，遇錯對照表單排查，耐心等待 Gradle/Ninja 構建完成。
