在硬件设备上运行应用

在将 Android 应用发布给用户之前，请务必在真实设备上进行测试。本页面介绍了如何设置开发环境和 Android 设备，以便通过 Android 调试桥 (ADB) 连接进行测试和调试。

设置用于开发的设备

在开始在设备上进行调试之前，请确定是要使用 USB 数据线还是 Wi-Fi 连接设备。然后执行以下操作：

  1. 在设备上，打开设置应用，选择开发者选项，然后启用USB 调试（如果适用）。

  2. 设置您的系统以检测您的设备。

    • ChromeOS：无需额外配置。
    • macOS：无需额外配置。
    • Windows：安装适用于 ADB 的 USB 驱动程序（如果适用）。如需安装指南及 OEM 驱动程序的链接，请参阅安装 OEM USB 驱动程序。

    • Ubuntu Linux：进行如下设置

      • 每个想要使用 ADB 的用户都需要加入 plugdev 组。如果您看到一条错误消息，提示您不在 plugdev 组中，请使用以下命令将自己添加到该组：
      sudo usermod -aG plugdev $LOGNAME

      组信息仅在登录时更新，因此您必须注销才能使此更改生效。重新登录后，您可以使用 id 命令检查自己是否已加入 plugdev 组。

      • 系统需要安装涵盖该设备的 udev 规则。android-sdk-platform-tools-common 软件包包含一组由社区维护的 Android 设备默认 udev 规则。要安装它，请使用以下命令：
      apt-get install android-sdk-platform-tools-common

使用 USB 连接到您的设备

完成设置并通过 USB 插入设备后，点击 Android Studio 中的运行 即可构建并运行您的应用。

您还可以使用 adb 发出命令，如下所示：

  • 通过从您的 android_sdk/platform-tools/ 目录运行 adb devices 命令，验证您的设备是否已连接。如果已连接，您会看到设备列出。
  • 使用 -d 标志发出任何 adb 命令，以指定您的设备为目标。

使用 Wi-Fi 连接到您的设备

Android 11 及更高版本支持通过 Android 调试桥 (ADB) 从工作站无线部署和调试您的应用。例如，您可以将可调试的应用部署到多台远程设备，而无需通过 USB 物理连接设备，从而避免了常见的 USB 连接问题，例如驱动程序安装问题。

Android 17 随 adb 37.0.0 一起引入了 adb Wi-Fi 2.0，它解决了旧版本中的许多易用性问题。值得注意的是，当设备连接到受信任的无线调试网络时，设备会自动连接到工作站。

要使用无线调试，您需要使用配对码将设备与工作站配对。首先，请完成以下步骤：

  1. 确保您的工作站和设备连接到同一个无线网络。
  2. 确保您的设备运行的是 Android 11 或更高版本。如需了解详情，请参阅检查并更新您的 Android 版本。
  3. 确保您已安装最新版本的 Android Studio。点此下载。
  4. 在工作站上，更新到最新版本的 SDK 平台工具。

要与设备配对，请按照以下步骤操作：

  1. 在设备上启用开发者选项。

  2. 在设备上，点击“无线调试”。

    pixel phone showing the Wireless debugging prompt.
    图 1. Google Pixel 手机上的无线调试提示。

  3. 允许在您的网络上进行无线调试。请注意，勾选在此网络上始终允许复选框会将此网络设为受信任的无线调试网络。一旦设备连接到该网络，它将始终允许无线调试。

    pixel phone showing the Wireless debugging systems setting.
    图 2. Google Pixel 手机上的无线调试设置。

  4. 打开 Android Studio，从运行配置菜单中选择使用 Wi-Fi 配对设备 (Pair Devices Using Wi-Fi)。

    Run configurations drop down
    图 3. 运行配置菜单。

  5. 系统会显示通过 Wi-Fi 配对设备 (Pair devices over Wi-Fi) 对话框，如图 4 所示。

    Pair devices over Wi-Fi popup window
    图 4. 通过 Wi-Fi 配对设备的对话框。

    或者，您也可以从设备管理器 (Device Manager) 配对设备。例如 My Pixel。

    Device Manager with device available for Wi-Fi pairing
    图 5. 显示可用于 Wi-Fi 配对的设备的设备管理器。

  6. 点击您要配对的设备上的 Pair。系统会显示设备配对对话框。

    1. 要通过二维码配对设备，请选择使用二维码配对设备 (Pair device with QR code) 并扫描二维码。
      Pair devices over Wi-Fi popup window
      图 6. 使用二维码配对设备的对话框。
    2. 要使用配对码配对设备，请从通过 Wi-Fi 配对新设备 (Pair new devices over Wi-Fi) 对话框中选择使用配对码配对设备 (Pair device with pairing code)。在您的设备上，选择使用配对码配对 (Pair using pairing code)。屏幕上会出现一个六位数的代码。当您的设备出现在通过 Wi-Fi 配对设备窗口中时，输入设备上显示的六位数代码，然后选择配对 (Pair)。
      Example pairing code entry
      图 7. 六位数配对码输入示例。

  7. 配对完成后，您可以尝试将应用部署到您的设备上。

要取消与工作站的配对，请转到设备上的无线调试。点击已配对设备下的工作站名称，然后选择忽略 (Forget)。或者，您也可以点击设备设置页面上的撤消 adb 调试授权，以取消与该工作站及所有之前已配对的其他工作站的配对。

设备镜像

您可以在 Android Studio 的运行中的设备 (Running Devices) 窗口中镜像您的物理设备。通过将设备的显示内容直接流式传输到 Android Studio，您可以直接使用 Studio IDE 执行常见操作，例如启动应用并与之交互、旋转屏幕、折叠和展开手机以及调节音量。

当计算机连接了启用了 USB 或无线调试功能的设备时，设备镜像功能始终可用。您可以使用运行中的设备窗口或设备管理器（视图 > 工具窗口 > 设备管理器）来启动和停止镜像。您还可以在设置（设置 > 工具 > 设备镜像）中自定义设备镜像的激活时间。

Running Devices UI

重定向音频

使用设备镜像时，您可以将连接的物理设备的音频重定向到计算机的扬声器或耳机。通过音频重定向，您可以让耳机保持连接到计算机，同时收听计算机和连接的手机的音频，而无需在不同设备之间手动重新连接。要启用音频重定向，请转到文件（macOS 上为 Android Studio）> 设置 > 工具 > 设备镜像，然后选择从本地设备重定向音频。请注意，对于运行 Android 12 或更高版本的 Firebase Test Lab 设备，无论设置如何，音频始终会被重定向。

已知问题

某些设备可能无法以足以支持设备镜像的比特率进行编码。在这种情况下，您可能会在运行中的设备窗口中看到错误，以及类似于以下的日志。

2023-06-01 15:32:22,675 [  56094]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - Too many video encoder errors:
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - encoder: c2.android.vp8.encoder
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - mime type: video/x-vnd.on2.vp8
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max resolution: 640x640
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - min resolution: 2x2
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - alignment: 2x2
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max frame rate: 960
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max frame rate for 288x640: 960
2023-06-01 15:32:22,870 [  56289]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max bitrate: 20000000
2023-06-01 15:32:22,871 [  56290]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - terminated with code 1

隐私声明

根据设备镜像设置，Android Studio 可以为任何已连接并配对的设备自动启动设备镜像。对于使用 adb tcpip 命令连接的设备，这可能会导致信息泄露，因为镜像信息和命令是通过非加密通道传输的。此外，Android Studio 使用非加密通道与 adb 服务器通信，因此镜像信息可能会被主机上的其他用户截获。

排查设备连接问题

如果您的设备无法连接到 Android Studio，请尝试以下步骤来解决问题：

使用连接助手进行排查

连接助手提供了分步说明，可帮助您设置并通过 ADB 连接使用设备。

要启动助手，请选择工具 > 排查设备连接问题 (Troubleshoot Device Connections)。

连接助手在助手面板的一系列页面中提供说明、上下文相关的控件以及已连接设备的列表。根据需要使用助手面板底部的下一步和上一步按钮来完成相关步骤：

  • 通过 USB 连接设备：连接助手首先会提示您通过 USB 连接设备，并提供一个重新扫描 USB 设备按钮，您可以在其中开始对已连接设备进行新的扫描。
  • 启用 USB 调试：连接助手随后会告诉您如何在设备上的开发者选项中启用 USB 调试。
  • 重启 ADB 服务器：如果您的设备列表中仍未显示您的设备，请使用连接助手最后一页上的重启 ADB 服务器按钮。重启 ADB 服务器也会导致 ADB 重新扫描设备。如果您的设备列表中仍未显示您的设备，请尝试下一节中的排查步骤。

解决 USB 连接问题

如果连接助手未通过 USB 检测到您的设备，请尝试以下排查步骤来解决问题：

检查 Android Studio 是否连接到 Android 模拟器

要检查该问题是否由 Android Studio 与 Android 模拟器之间的连接问题引起，请按照以下步骤操作：

  1. 打开设备管理器。
  2. 如果您还没有 AVD，请创建一个新的 AVD。
  3. 使用您的 AVD 运行模拟器。
  4. 执行以下操作之一：
    • 如果 Android Studio 无法连接到模拟器，请下载最新的 SDK 平台工具，然后重试。
    • 如果模拟器成功启动，请按照下一节所述检查 USB 数据线。

检查 USB 数据线

要检查该问题是否由损坏的 USB 数据线引起，请按照本节中的步骤操作。

如果您有另一根 USB 数据线

  1. 使用备用数据线连接设备。
  2. 检查连接助手现在是否可以检测到设备。
  3. 如果未检测到设备，请尝试重新使用原来的数据线。
  4. 如果仍然未检测到设备，请假定问题出在设备上，并按照下一节所述检查设备是否已针对开发进行设置。

如果您没有其他 USB 数据线，但有另一台 Android 设备

  1. 将第二台设备连接到您的计算机。

  2. 如果连接助手可以检测到第二台设备，则假定问题出在主要设备上，并检查该设备是否已针对开发进行设置。

    如果未检测到第二台设备，则问题可能出在 USB 数据线上。

检查设备是否已针对开发进行设置

要检查该问题是否由设备上的设置引起，请按照以下步骤操作：

  1. 按照设置用于开发的设备一节中的步骤操作。
  2. 如果这不能解决问题，请联系设备 OEM 的客户支持以获取帮助。告诉客户支持代表该设备无法使用 ADB 连接到 Android Studio。

解决无线连接问题

如果您在通过无线方式连接设备时遇到问题，请尝试以下排查步骤来解决问题：

检查您的工作站和设备是否满足前提条件

检查工作站和设备是否满足前提条件。

查看 adb 排查指南

遵循 adb 排查指南。

RSA 安全密钥

当您将运行 Android 4.2.2 (API 级别 17) 或更高版本的设备连接到计算机时，系统会显示一个对话框，询问是否接受 RSA 密钥以允许通过此计算机进行调试。此安全机制可保护用户设备，因为除非您能够解锁设备并确认该对话框，否则无法执行 USB 调试和其他 adb 命令。