Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

編譯 Android 版本

也參考

本頁說明如何從原始碼編譯 Android 匯出範本二進位檔。如果你的需求是將專案匯出到 Android，請參閱 為 Android 匯出。

注意

在大多數情況下，使用內建的部署工具與匯出範本即可滿足需求。手動編譯 Android APK 通常僅用於自訂建置或為部署工具製作自訂套件。

此外，在建置自訂匯出範本之前，仍需遵循 為 Android 匯出 教學中提到的步驟。

系統需求

欲於 Windows、Linux 或 macOS 進行編譯，需具備以下條件：

  • Python 3.9+.

  • SCons 4.4+ build system.

  • Android SDK

    • To install the Android SDK, follow the steps here.

    • 在 Linux 上，請勿使用由發行版套件庫提供的 Android SDK，因為這些版本通常過舊。

    • 在 macOS 上，請勿使用 Homebrew 安裝的 Android SDK，因其安裝路徑不統一。

  • Gradle（若尚未安裝，將自動下載並安裝）。

  • JDK 17（可用 OpenJDK 或 Oracle JDK）。

    • You can download a build from Adoptium.

也參考

如需取得 Godot 編譯所需的原始碼，請參閱 取得原始碼。

關於 Godot 使用 SCons 的基本說明，請參閱 建置系統介紹。

建置系統設定

  • 請將環境變數 ANDROID_HOME 指向 Android SDK 的路徑。若你下載的是 Android 命令列工具，請設為你解壓縮 ZIP 檔案後的目錄。

    • Windows：按下 Windows + R，輸入「control system」，在左側點擊 進階系統設定，接著於出現的視窗中點擊 環境變數。

    • Linux 或 macOS：請將 export ANDROID_HOME="/path/to/android-sdk" 加入至你的 .bashrc 或 .zshrc，其中 /path/to/android-sdk 請換成 SDK 的根目錄路徑。

  • 設定好 SDK 與環境變數後，請**重新啟動終端機**以套用變更。若你使用的是有整合終端機的 IDE，也請一併重啟該 IDE。

  • 執行 scons platform=android。若失敗，請回頭檢查各步驟。若設定正確，NDK 會開始下載。若你要編譯 GDExtension，必須先編譯引擎以下載 NDK，之後才能編譯 GDExtension。

建置匯出範本

Godot 需要三個 Android 匯出範本：最佳化的「release」範本（android_release.apk）、除錯範本（android_debug.apk）、以及 Gradle 建置用範本（android_source.zip）。自 2019 年 8 月起 Google 規定所有 APK 必須包含 ARMv8（64 位元）函式庫，因此下方指令會同時產生包含 ARMv7 與 ARMv8 函式庫的範本。

透過在 Godot 原始碼根目錄下，使用以下參數呼叫 SCons，即可編譯標準匯出範本：

  • 釋出範本（於匯出時未勾選 Debugging Enabled 時使用）

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64 generate_android_binaries=yes

  • 除錯範本（於匯出時有勾選 Debugging Enabled 時使用）

scons platform=android target=template_debug arch=arm32
scons platform=android target=template_debug arch=arm64 generate_android_binaries=yes

產生的範本將會位於 bin 目錄下：

  • bin/android_release.apk 對應釋出範本

  • bin/android_debug.apk 對應除錯範本

  • bin/android_source.zip 對應 Gradle 建置範本

備註

  • 若你更動了建置的架構清單, 請記得在 最後 一個建置的架構加上 generate_android_binaries=yes , 這樣樣板檔案才能在建置結束後正確產生。

  • To enable dev build (for use when troubleshooting) in the generated templates, add the dev_build=yes parameters to the SCons command.

  • 若需於產生的範本中包含除錯符號，請於 SCons 指令加上 debug_symbols=yes 參數。

    • 另外也可加入 separate_debug_symbols=yes，將除錯符號輸出到獨立的 *-native-debug-symbols.zip 壓縮檔中。

也參考

若要啟用 Vulkan 驗證層，請參閱 Android 上的 Vulkan 驗證層。

支援 x86 裝置

若想同時支援 x86 與 x86_64 裝置，請於以 Gradle 建置 APK 前，分別以 arch=x86_32 與 arch=x86_64 參數再次執行 SCons 指令。以釋出範本為例：

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64
scons platform=android target=template_release arch=x86_32
scons platform=android target=template_release arch=x86_64 generate_android_binaries=yes

這樣會建立能在所有平台運作的範本二進位檔。專案最終匯出的檔案大小會根據你選擇支援的平台而定，也就是未啟用的平台將自動被移除。

清除產生的匯出範本

你可以用以下指令移除產生的匯出範本：

cd platform/android/java
# On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

使用匯出範本

Godot 需要使用與編輯器相同版本（或 Commit）編譯的釋出與除錯二進位檔。若使用官方編輯器執行檔，請確保安裝的匯出範本版本相符，或自行以相同版本建置。

匯出遊戲時，Godot 會以範本為基底，並依需求更新其內容。

安裝範本

新編譯的範本（android_debug.apk、android_release.apk、android_source.zip）必須以正確名稱複製到 Godot 的範本資料夾。範本資料夾位置如下：

  • Windows：%APPDATA%\Godot\export_templates\<版本>\

  • Linux：$HOME/.local/share/godot/export_templates/<版本>/

  • macOS：$HOME/Library/Application Support/Godot/export_templates/<版本>/

<版本> 格式為 major.minor[.patch].status，數值取自 Godot 原始碼中的 version.py``（例如 ``4.1.3.stable 或 4.2.dev）。你也需要將相同的版本字串寫入匯出範本同層的 version.txt 檔案。

但如果你正在撰寫自訂模組或自訂 C++ 程式碼，建議在專案的匯出選單中把你產生的樣板二進位檔設定成自訂匯出樣板。你必須啟用 Advanced Options（進階選項） 才能進行此設定。

../../../_images/andtemplates.webp

此時甚至不必複製檔案，只需直接參照 Godot 原始碼資料夾下的 bin\ 內結果檔案，下次建置時就會自動使用該自訂範本。

編譯 Godot 編輯器

於 Godot 原始碼根目錄執行 SCons 並帶入下列參數，即可編譯編輯器：

scons platform=android arch=arm32 production=yes target=editor
scons platform=android arch=arm64 production=yes target=editor
scons platform=android arch=x86_32 production=yes target=editor
scons platform=android arch=x86_64 production=yes target=editor generate_android_binaries=yes

  • 你可以加上 dev_build=yes 參數，產生 Godot 編輯器的開發版本。

  • 你可以加上 debug_symbols=yes 參數，於產生的建置中包含除錯符號。

    • Note that you can include separate_debug_symbols=yes to the last architecture you're building, to generate the debug symbols in a separate *-native-debug-symbols.zip file.

  • 你可以根據目標裝置略過某些架構，以加快編譯速度。

請記得在 最後 一個建置的架構加上 generate_android_binaries=yes , 這樣二進位檔才能在建置完成後正確產生。

產生的編輯器二進位檔會位於 bin/android_editor_builds/。

移除編輯器二進位檔

你可以用以下指令移除產生的編輯器二進位檔：

 cd platform/android/java
 # On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

安裝 Godot 編輯器 APK

於已啟用開發者選項的 Android 裝置上，以充電線連接至電腦的 USB/USB-C 連接埠。開啟終端機／命令提示字元，並於根目錄下執行以下指令：

adb install ./bin/android_editor_builds/android_editor-android-debug.apk

疑難排解

SCons 未顯示平台

請再次確認你有設定 ANDROID_HOME 環境變數。必須設定這個環境變數，平台才會出現在 SCons 偵測列表中。詳情請參閱 建置系統設定。

應用程式無法安裝

Android 可能會提示應用程式未正確安裝，請依下列步驟檢查：

  • 檢查除錯金鑰儲存區是否有正確產生。

  • 檢查 jarsigner 執行檔是否為 JDK 8 的版本。

若仍然失敗，請開啟命令列並執行 logcat：

adb logcat

安裝應用程式時檢查 logcat 輸出，錯誤訊息應會顯示於其中。若無法自行解決，請尋求協助。

應用程式立即退出

若應用程式可啟動但立即退出，可能原因如下：

  • 請務必使用與編輯器相同版本的匯出範本；若有更新 Godot 版本， 也必須 一併更新範本。

  • libs/<arch>/ 資料夾內缺少 libgodot_android.so，其中 <arch> 為裝置架構。

  • 裝置架構與匯出範本不符。請確認範本有針對該裝置架構建置，且匯出設定有包含對此架構的支援。

不論何種狀況，adb logcat 應也會顯示錯誤原因。