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...

單鍵部署

什麼是一鍵式部署？

這個功能會在有正確配置平台且將支援的裝置連接到電腦上後彈出。由於很多地方都有可能出問題 (平台可能未正確設定、可能沒正確安裝 SDK、裝置可能為正確設定…等)，所以讓使用者知道有單鍵部署這功能存在也不錯。

有些平台 (在本文撰寫時，只有 Android) 可以在 USB 裝置連接到電腦上時自動偵測，並提供使用者在該裝置上自動匯出、安裝與 (以除錯模式) 執行專案的功能，用業界的流行語來說，就是「單鍵部署」。

備註

在匯出對話方塊中新增匯出範本並標記為**可執行**後便可使用一鍵部署。你可以同時將多個匯出預設項標記為可執行，但同一平臺被標記為可執行的只能有一個。如果你把該平臺的第二個預設項標記為可執行，其它預設項的標記會被取消。

支援的平台

  • Android: 將在匯出專案時啟用除錯，並在連接的裝置上運作。

    • 另外，在建置自定匯出樣板前，依然必須依照 為 Android 匯出 中所提到的步驟進行。

    • 如果你連接的裝置超過一台，Godot會詢問你想匯出專案到哪台裝置。

  • iOS： 匯出專案時啟用除錯，並在已連接的裝置上執行。

    • 請務必依照 為 iOS 匯出 中描述的步驟進行。否則，一鍵部署按鈕將不會出現。

    • 每當使用新的 Bundle Identifier 時，請先匯出專案，再用 Xcode 開啟並至少建置一次，以建立新的描述檔，或直接在 Apple Developer 帳號後台建立描述檔。

    • 如果你連接的裝置超過一台，Godot會詢問你想匯出專案到哪台裝置。

  • 桌面平台： 匯出專案並啟用除錯，透過 SSH 在遠端電腦上執行。

  • Web： 會啟動本地網頁伺服器，並在預設瀏覽器中執行匯出的專案。預設僅能在 localhost 存取。如需讓其他裝置存取，請參考 疑難排解。

單鍵部署

  • Android:

    • 在您的行動裝置上啟用開發人員模式，然後在裝置的設定中啟用 USB 除錯。

    • 啟用 USB 除錯後，使用 USB 纜線將裝置連接到您的 PC。

    • It's also possible to one-click deploy via wireless ADB instead of with a USB cable. In order to do this, it is necessary to:

      • Enable wireless debugging on the device: Settings > Developer options > Debugging

      • Connect to the same Wi-Fi network on your mobile device and PC.

      • Click Pair device with pairing code: (can be accessed via long press on wireless debugging) to display IP, port, and pairing code.

      • On your PC, enter the command adb pair <ip address>:<port> and provide the pairing code when prompted. If adb is not recognized, you may need to add the android-sdk's platform-tools folder to your PATH or execute this command from there.

      • You can verify the ADB device is successfully connected by entering adb devices in the terminal.

  • iOS：

    • 安裝 Xcode，接受 Xcode 授權條款，並使用你的 Apple Developer 帳號登入。

    • 如果你使用的是 Xcode 14 或更早版本，請安裝 ios-deploy，並在編輯器設定中設定 ios-deploy 的路徑（請見「匯出 ⇾ iOS ⇾ iOS Deploy」）。

    • 如要在實體裝置上執行：

      • 請將你的行動裝置與 Mac 配對。

      • 在裝置上啟用開發者模式。

      • 裝置可透過 USB 或區域網路連線。

      • 請確保裝置與電腦在同一區域網路，並於編輯器設定中選擇正確的網路介面（請見「網路 ⇾ 除錯 ⇾ 遠端主機」）。預設情況下，編輯器僅監聽 localhost 連線。

    • 請確保裝置螢幕已解鎖。

  • 桌面平台：

    • 啟用 SSH 遠端部署，並於專案匯出設定中設定連線參數。

  • 請確認針對目標平台 (Android、iOS 或 Web) 存在一個標記為 可執行 的匯出預設集。

  • 如果這些都配置正確並且沒有報告有錯，編輯器右上角會出現平臺對應的圖示。

  • 點擊該按鈕一鍵匯出到所需的平臺。

../../_images/remote_debug.webp

疑難排解

Android

如果你在命令列中運作 adb devices 時無法在裝置列表中看到該裝置，那麼 Godot 就也無法看到。要解決這個問題：

  • 請檢查是否啟用了 USB 並在該裝置上授權。請嘗試解鎖你的裝置，如果有任何授權的彈框的話請接受。如果你沒有看到這樣的彈框，在 PC 上執行 adb devices 應該就會在該裝置上彈出授權提示。

  • 請嘗試在該裝置的開發者設定中`撤銷除錯授權 <https://stackoverflow.com/questions/23081263/adb-android-device-unauthorized>`__，然後再重試這些步驟。

  • 請嘗試使用 USB 除錯而不是無線除錯，反之亦然。有時候換種方法就能更好地工作。

  • 在 Linux 上，你可能缺少所需的 udev 規則，導致你的裝置無法被識別。

Web

預設情況下，編輯器啟動的網頁伺服器僅能從 localhost 存取。也就是說，區網內或網際網路上的其他裝置（即使路由器有設定埠轉發）都無法存取該伺服器。這是為了安全考量，以避免在你測試時，其他裝置也能存取匯出的專案。此外，綁定在 localhost 也能避免在 Web 平台一鍵部署時出現防火牆提示。

若要讓本地網頁伺服器可在區域網路中存取，請將 匯出 > Web > HTTP Host 編輯器設定改為 0.0.0.0 。此外，須啟用 匯出 > Web > 使用 TLS ，因 SharedArrayBuffer 需要安全連線才能運作（ 除非 連線目標是 localhost ）。但由於其他用戶端會連線到遠端裝置，因此此處必須啟用 TLS。

若要讓本地網頁伺服器能從網際網路存取，還需將編輯器設定中「匯出 > Web > HTTP Port」（預設為 8060）透過路由器以 TCP 進行埠轉發。通常需從路由器網頁介面設定，為指定埠口新增 NAT 規則。若屬 IPv6 連線，則需在路由器的 IPv6 防火牆允許該埠。同樣，必須啟用「匯出 > Web > 使用 TLS」。

備註

啟用 使用 TLS 後，瀏覽器會因 Godot 採用臨時自簽憑證顯示警告。你可以放心忽略，點擊 進階 後選擇 繼續前往（網址） 即可。

如果你有瀏覽器信任的 SSL/TLS 憑證，可以在「匯出 > Web > TLS 金鑰」和「匯出 > Web > TLS 憑證」指定金鑰和憑證檔案路徑。只有當專案以 TLS 憑證所涵蓋的網域名存取時，此功能才會生效。

警告

在不同專案中使用一鍵部署時，可能會顯示成先前編輯的專案。這是因為 service worker 快取不會自動清除。請參考 疑難排解 以取消註冊 service worker，藉此清除快取並解決問題。