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 导出预设项并且标记为可执行之后，Godot 就可以检测到有 USB 设备连接到了电脑上，并且允许用户在该设备上自动导出、安装、然后运行（调试模式的）项目。这个功能就叫一键部署。

备注

一键部署只有在导出对话框中添加导出预设并标记为可执行后才可使用。你可以同时将多个导出预设标记为可执行，但同一平台上被标记为可执行的预设只能有一个。如果你把一个平台的第二个预设标记为可执行，先前预设的标记会被取消。

支持的平台

  • Android：将在导出项目时启用调试，并在连接的设备上运行。

    • 请确认已经按照为 Android 导出中提到的步骤进行操作，否则不会出现一键部署按钮。

    • 如果你连接的设备超过一台，Godot 会询问你想导出项目到哪台设备。

  • iOS：将在导出项目时启用调试，并在连接的设备上运行。

    • 请确认已经按照为 iOS 导出中提到的步骤进行操作，否则不会出现一键部署按钮。

    • 对于每个新的捆绑包标识符，导出项目，在 Xcode 中打开它，并至少构建一次以创建新的配置文件或在 Apple 开发者帐户仪表板中创建配置文件。

    • 如果你连接的设备超过一台，Godot 会询问你想导出项目到哪台设备。

  • Desktop platforms（桌面平台）：导出启用了调试功能的项目，并通过 SSH 在远程计算机上运行。

  • Web：通过打开默认 Web 浏览器启动本地 Web 服务器并运行导出的项目。默认情况下，这只能在 localhost 上访问。请参阅故障排除以了解如何在远程设备上访问导出的项目。

使用一键部署

  • Android：

    • 请在移动设备上打开开发者模式，然后在设备的设置中启用 USB 调试。

    • 启用 USB 调试后，请将设备通过 USB 线缆连接到 PC。

    • 除了用 USB 数据线连接，也可以通过无线 ADB 实现一键部署。想要做到这一点，你需要：

      • 在设备上启用无线调试：Settings > Developer options > Debugging

      • 确保你的移动设备（手机）和电脑连接到同一个 Wi-Fi 网络。

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

      • 在电脑上输入命令 adb pair <ip address>:<port> ，然后在提示时输入配对码。如果系统提示无法识别 adb 命令，你可能需要把 Android SDK 里的 platform-tools 文件夹添加到系统的 PATH 环境变量中，或者直接在该文件夹目录下执行这条命令。

      • 你可以在终端里输入 adb devices ，来确认 ADB 设备是否已经成功连接。

  • iOS：

    • 安装 Xcode、接受 Xcode 授权协议并使用你的 Apple 开发者账户登录。

    • 如果你使用的是 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 应该就会在该设备上弹出授权提示。

  • 请尝试在该设备的开发者设置中撤销调试授权，然后再重试这些步骤。

  • 请尝试使用 USB 调试而不是无线调试，反之亦然。有时候一种方法比另一种效果更好。

  • 在 Linux 上，你可能缺少所需的 udev 规则，导致你的设备无法被识别。

Web

默认情况下，编辑器启动的 Web 服务器只能从 localhost 访问。这意味着本地网络或 Internet 上的其他设备（如果路由器上设置了端口转发）无法访问 Web 服务器。这样做是出于安全原因，因为你可能不希望其他设备在测试导出的项目时能够访问它。绑定 localhost 还可以防止在使用 Web 平台的一键部署时出现防火墙弹出窗口。

要使本地 Web 服务器可通过本地网络访问，你需要将导出 > Web > HTTP 主机编辑器设置更改为 0.0.0.0。你还需要启用导出 > Web > 使用 TLS，因为除非连接到 localhost，SharedArrayBuffer 需要使用安全连接才能工作。然而，由于其他客户端将连接到远程设备，这里绝对需要使用 TLS。

要使本地 Web 服务器可通过 Internet 访问，你还需要在路由器上转发编辑器设置中指定的导出 > Web > HTTP 端口的 TCP 端口（默认为 8060）。这通常是通过访问路由器的 Web 界面，然后为相关端口添加 NAT 规则来完成的。对于 IPv6 连接，你应该在路由器的 IPv6 防火墙中允许该端口。与局域网络设备一样，你还需要启用导出 > Web > 使用 TLS。

备注

当启用了使用 TLS选项时，你的网页浏览器会显示警告，因为 Godot 会使用一个临时的自签名证书。你可以安全地忽略它，并通过点击高级然后选择继续前往（地址）来绕过这个警告。

如果你有一个被浏览器信任的 SSL/TLS 证书，你可以在导出 > Web > TLS 密钥和导出 > Web > TLS 证书中指定密钥和证书文件的路径。这仅在项目是通过 TLS 证书中包含的域名访问时才有效。

警告

在不同项目中使用一键部署时，可能会显示之前编辑过的项目而非当前项目。这是由于服务工作线程的缓存未被自动清除所致。有关如何注销服务工作线程以有效清除缓存并解决此问题的说明，请参阅故障排除。