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 匯出

也參考

這個頁面描述的是如何將 Godot 專案匯出到 Android。如果你想要找的是從源碼編譯編輯器或匯出範本二進位檔案，請閱讀 編譯 Android 版本。

匯出至 Android 的需求比為 Android 編譯 Godot 還來得少。下列為設定 SDK 與 Godot 所需的詳細步驟。

注意

自 Godot 4.2 起，C# 專案也可以匯出到 Android，但目前僅為實驗性支援，且 有部分限制。

Setup on Android

When exporting to Android from the Android editor, you do not need to install OpenJDK or the Android SDK when exporting to Android, regardless of the export method used (pre-built APK or Gradle build).

However, if you are performing a Gradle build, you will need to follow some steps described in 適用於 Android 的 Gradle 建置.

You can then skip to 提供起動器圖示.

Automatic build setup on Windows, macOS, and Linux

Starting with Godot 4.8, the editor provides support for automatically setting up the Android and Java SDKs. The manual setup instructions are still provided in Manual build setup on Windows, macOS, and Linux for those that may need it.

The feature can be enabled from two locations:

  • From the Project menu, select Setup Android Build....

../../_images/setup_android_build_screenshot.webp

  • Alternatively, from the Export Presets window a warning and clickable link will show when an Android preset is added and the Android and/or Java SDKs are not set up.

../../_images/setup_android_build_from_export_presets_screenshot.webp

Clicking on either will launch several dialogs that will prompt for, download, and install the Android and Java SDKs in a location specific to the Godot editor.

Manual build setup on Windows, macOS, and Linux

安裝 OpenJDK 17

下載並安裝 OpenJDK 17。

備註

也支援更高版本的 JDK，但建議使用 JDK 17 以獲得最佳相容性與穩定性。

下載 Android SDK

Download and install the Android SDK using the Android CLI.

  • Once the Android CLI is installed, run the following command from a terminal to complete the setup process:

android sdk install platform-tools build-tools/36.1.0 platforms/android-36 cmdline-tools/latest ndk/29.0.14206865 cmake/3.22.1

備註

如果你使用的是 Linux，請勿使用發行版本軟體庫提供的 Android SDK，因為它通常是過時的。

在 Godot 中設定

進入編輯器設定畫面 (在 macOS 上，位於 Godot 選單下；或在其他平台上，位於編輯器選單下)。這個畫面包含針對電腦中使用者帳戶的編輯器設定 (這是獨立於專案的)。

../../_images/editorsettings.webp

下拉至 Android 設定的部分：

../../_images/android_editor_settings.webp

在此畫面中，需要設定 2 個路徑：

  • Java SDK Path 應設為 OpenJDK 17 安裝路徑。

  • Android SDK Path should be the location where the Android SDK was installed. This directory should contain platform-tools/adb. - For example %LOCALAPPDATA%\Android\Sdk\ on Windows or /Users/$USER/Library/Android/sdk/ on macOS.

設定好了之後，就準備好能匯出到 Android 了！

備註

如果你遇到 “Could not install to device” 的錯誤，請確認裝置上未安裝使用了相同Android包名（但使用不同金鑰進行簽章）的應用。

如果裝置上安裝了 Android 包名相同但簽章金鑰不同的應用，你**必須**先在該 Android 裝置詢問時選擇刪除該應用，但後再重新匯出到 Android。

提供起動器圖示

啟動器圖示是給 Android 起動器應用程式將程式顯示給使用者看的圖示。Godot 中只需要提供高解析度圖示 (用於 xxxhdpi 密度螢幕)，就會自動產生各個低解析度的版本。

圖示有三種：

  • 主圖示： 即「經典」的圖示。會用於最高至 Android 8 (Orea) 的 Android 版本。必須至少有 192×192 px。

  • Adaptive Icons: Starting from Android 8 (inclusive), Adaptive Icons were introduced. Applications will need to include separate background and foreground icons to have a native look. The user's launcher application will control the icon's animation and masking. Must be at least 432×432 px.

  • 主題圖示 (選用)： 從 Android 13 (含) 開始，推出了主題圖示。應用程式需要包含一個單色圖示才能啟用此功能。使用者的啟動器應用程式將會控制圖示的主題。必須至少為 432x432 像素。

也參考

在設計調適性圖示時，遵守一些規則也很重要。Google Design 發表了一篇很棒的文章 (英文) ，有助於瞭解這些規則以及調適性圖示的一些限制。

警示

調適性圖示設計規則中最重要的一點是要將圖示的關鍵元素放在安全區域內，即為正中間有直徑 66dp 的圓圈 (xxxhdpi 下為 264 像素)，才可避免圖示被起動器給剪裁。

如果您沒有提供要求的圖示 (Monochrome 除外)，Godot 將會透過使用備用鏈來取代它們，當目前一個失敗時會嘗試下一個：

  • Main Icon： 提供的主圖示 -> 專案圖示 -> 預設 Godot 主圖示。

  • Adaptive Icon Foregrond: 提供的前景圖示 -> 提供的主圖示 -> 專案圖示 -> 預設 Godot 前景圖示。

  • Adaptive Icon Background: 提供的背景圖示 -> 預設 Godot 背景圖示。

強烈建議提供所有需要的圖示，並至少要有指定的解析度。只有這樣才能讓應用程式在所有 Android 裝置與版本中看起來好看。

為 Google Play Store 匯出

All new apps uploaded to Google Play after August 2021 must be an AAB (Android App Bundle) file. To export an AAB file you need to set up 適用於 Android 的 Gradle 建置.

將 AAB 或 APK 上傳到 Google Play 商店時，必須使用非除錯用的 keystore 檔案簽章。你可以用下列指令產生：

keytool -v -genkey -keystore mygame.keystore -alias mygame -keyalg RSA -validity 10000

此 keystore 及金鑰會用來驗證你的開發者身份，請務必記住密碼並妥善保存！建議僅使用英數大小寫，不建議特殊符號，以免發生錯誤。更多關於應用簽章的細節可參考 Google 官方說明：app signing。

接著在 Android 匯出預設中填寫下列表格：

../../_images/editor-export-presets-android.webp

  • Release： 輸入剛才產生的金鑰儲存區檔案位置。

  • Release User： 以金鑰別名取代。

  • Release Password： 金鑰密碼，請注意，目前金鑰儲存區密碼與金鑰的密碼必須相同。

設定 APK 名稱時也別忘了取消勾選 [Export With Debug] 勾選框。

../../_images/export-with-debug-button.webp

最佳化檔案大小

You can optimize the size of your application by compiling an Android export template with only the features you need. See 最佳化建置檔案大小 for more information.

Performing a custom Gradle build

If you need to modify the template's Java code or integrate with third-party Android SDKs, you may want to use a custom Gradle build instead of the default pre-built APK template. This allows you to have more control over the build process and the generated project, and you can use it as a base for further customization.

See 適用於 Android 的 Gradle 建置 for guidance on setting up a custom Gradle build.

環境變數

您可以使用下列環境變數在編輯器外部設定匯出選項。在匯出過程中，這些值會覆寫您在匯出選單中設定的值。

Android匯出環境變數

匯出選項

環境變數

加密／加密金鑰

GODOT_SCRIPT_ENCRYPTION_KEY

選項/金鑰庫/除錯

GODOT_ANDROID_KEYSTORE_DEBUG_PATH

選項/金鑰庫/除錯使用者

GODOT_ANDROID_KEYSTORE_DEBUG_USER

選項/金鑰庫/除錯密碼

GODOT_ANDROID_KEYSTORE_DEBUG_PASSWORD

選項/金鑰庫/發布

GODOT_ANDROID_KEYSTORE_RELEASE_PATH

選項/金鑰庫/釋放使用者

GODOT_ANDROID_KEYSTORE_RELEASE_USER

選項/金鑰庫/釋放密碼

GODOT_ANDROID_KEYSTORE_RELEASE_PASSWORD

匯出選項

完整的可用匯出選項列表請見 EditorExportPlatformAndroid 類別參考。