Android 调试桥 (adb)

Android 调试桥（adb）是一个多功能的命令行工具，可让您与设备通信。 adb 命令有助于执行各种设备操作，例如安装和调试应用。 adb 提供对 Unix shell 的访问权限，您可以使用该 shell 在设备上运行各种命令。它是一个客户端-服务器程序，包括三个组件

  • 客户端，发送命令。客户端在您的开发机器上运行。您可以通过发出 adb 命令从命令行终端调用客户端。
  • 守护程序 (adbd)，在设备上运行命令。守护程序在每个设备上作为后台进程运行。
  • 服务器，管理客户端和守护程序之间的通信。服务器在您的开发机器上作为后台进程运行。

adb 包含在 Android SDK 平台工具包中。使用 SDK 管理器 下载此程序包，它会将其安装在 android_sdk/platform-tools/ 中。如果您想要独立的 Android SDK 平台工具包，请从此处下载。

有关通过 adb 连接设备以供使用的信息，包括如何使用连接助手解决常见问题，请参阅 在硬件设备上运行应用。

adb 的工作原理

启动 adb 客户端时，客户端首先检查是否已运行 adb 服务器进程。如果没有，它将启动服务器进程。服务器启动后，它将绑定到本地 TCP 端口 5037 并侦听从 adb 客户端发送的命令。

注意：所有 adb 客户端都使用端口 5037 与 adb 服务器通信。

然后，服务器建立到所有正在运行的设备的连接。它通过扫描 5555 到 5585 范围内的奇数端口来查找模拟器，这是前 16 个模拟器使用的范围。在服务器找到 adb 守护程序 (adbd) 的位置时，它会建立到该端口的连接。

每个模拟器都使用一对连续的端口 - 一个偶数端口用于控制台连接，一个奇数端口用于 adb 连接。例如

模拟器 1，控制台：5554
模拟器 1，adb：5555
模拟器 2，控制台：5556
模拟器 2，adb：5557
依此类推。

如所示，连接到端口 5555 上的 adb 的模拟器与控制台侦听端口 5554 的模拟器相同。

服务器建立到所有设备的连接后，您可以使用 adb 命令访问这些设备。由于服务器管理到设备的连接并处理来自多个 adb 客户端的命令，因此您可以从任何客户端或从脚本控制任何设备。

在您的设备上启用 adb 调试

要在通过 USB 连接的设备上使用 adb，您必须在设备系统设置中的开发者选项下启用USB 调试。在 Android 4.2（API 级别 17）及更高版本中，开发者选项屏幕默认情况下处于隐藏状态。要使其可见，请启用开发者选项。

您现在可以使用 USB 连接您的设备。您可以通过从 android_sdk/platform-tools/ 目录执行 adb devices 来验证您的设备是否已连接。如果已连接，您将看到设备名称列为“设备”。

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

有关通过 USB 连接到设备的更多信息，请阅读在硬件设备上运行应用。

通过 Wi-Fi 连接到设备

注意：以下说明不适用于运行 Android 11（API 级别 30）的 Wear 设备。有关更多信息，请参阅调试 Wear OS 应用指南。

Android 11（API 级别 30）及更高版本支持使用 Android Debug Bridge (adb) 从您的工作站无线部署和调试您的应用。例如，您可以将可调试的应用部署到多个远程设备，而无需通过 USB 物理连接您的设备。这消除了处理常见 USB 连接问题（例如驱动程序安装）的需要。

在开始使用无线调试之前，请执行以下操作

  • 确保您的工作站和设备连接到同一个无线网络。

  • 确保您的设备运行 Android 11（API 级别 30）或更高版本（适用于手机）或 Android 13（API 级别 33）或更高版本（适用于电视和 Wear OS）。有关更多信息，请参阅检查和更新您的 Android 版本。

  • 如果使用 IDE，请确保您已安装最新版本的 Android Studio。您可以在此处下载它。

  • 在您的工作站上，更新到最新版本的SDK 平台工具。

要使用无线调试，您必须使用 QR 码或配对码将您的设备与工作站配对。您的工作站和设备必须连接到同一个无线网络。要连接到您的设备，请按照以下步骤操作

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

  2. 打开 Android Studio，然后从运行配置菜单中选择使用 Wi-Fi 配对设备。

    Run configurations dropdown menu
    图 1. 运行配置菜单。

    使用 Wi-Fi 配对设备窗口会弹出，如图 2 所示。

    Screenshot of the pair devices over Wi-Fi popup window
    图 2. 使用 QR 码或配对码配对设备的弹出窗口。

  3. 在您的设备上，点击无线调试并配对您的设备

    Screenshot of a pixel phone showing the Wireless debugging systems setting.
    图 3. Google Pixel 手机上无线调试设置的屏幕截图。

    1. 要使用 QR 码配对您的设备，请选择使用 QR 码配对设备并扫描从图 2 所示的使用 Wi-Fi 配对设备弹出窗口获取的 QR 码。

    2. 要使用配对码配对您的设备，请从使用 Wi-Fi 配对设备弹出窗口中选择使用配对码配对设备。在您的设备上，选择使用配对码配对并记下提供的六位数代码。当您的设备出现在使用 Wi-Fi 配对设备窗口中时，您可以选择配对并输入设备上显示的六位数代码。

      Screenshot of example pin code entry
      图 4. 六位数代码输入示例。

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

    要配对不同的设备或忘记工作站上的当前设备，请在设备上导航到无线调试。点击已配对设备下的工作站名称，然后选择忘记。

  5. 如果您想快速打开和关闭无线调试，您可以使用无线调试的快速设置开发者磁贴，位于开发者选项>快速设置开发者磁贴中。

    Screenshot of Quick settings developer tiles from a Google Pixel phone.
    图 5.快速设置开发者磁贴设置允许您快速打开和关闭无线调试。

使用命令行进行 Wi-Fi 连接

或者，要使用命令行连接到您的设备（无需 Android Studio），请按照以下步骤操作

  1. 在您的设备上启用开发者选项，如前所述。

  2. 在您的设备上启用无线调试，如前所述。

  3. 在您的工作站上，打开终端窗口并导航到android_sdk/platform-tools。

  4. 通过选择使用配对码配对设备查找您的 IP 地址、端口号和配对码。记下设备上显示的 IP 地址、端口号和配对码。

  5. 在您的工作站的终端上，运行adb pair ipaddr:port。使用上面的 IP 地址和端口号。

  6. 出现提示时，输入配对码，如下所示。

    Screenshot of pairing on the command line.
    图 6. 一条消息指示您的设备已成功配对。

解决无线连接问题

如果您在无线连接到设备时遇到问题，请尝试以下故障排除步骤以解决问题。

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

检查工作站和设备是否满足本节开头列出的先决条件。

检查其他已知问题

以下是无线调试（使用 adb 或 Android Studio）的当前已知问题列表以及如何解决它们

  • Wi-Fi 未连接：安全 Wi-Fi 网络（例如公司 Wi-Fi 网络）可能会阻止点对点连接，并且不允许您通过 Wi-Fi 连接。尝试使用电缆或其他（非公司）Wi-Fi 网络连接。在进行初始 USB 连接后，通过 tcp/ip 使用adb connect ip:port进行无线连接是另一种选择，以防诉诸非公司网络成为一种选择。

  • adb 通过 Wi-Fi 有时会自动关闭：如果设备切换 Wi-Fi 网络或断开网络连接，则可能会发生这种情况。要解决此问题，请重新连接到网络。

  • 配对成功后设备未连接：adb 依赖于 mDNS 来发现并自动连接到已配对的设备。如果您的网络或设备配置不支持 mDNS 或已禁用它，则需要使用adb connect ip:port手动连接到设备。

在进行初始 USB 连接后，使用设备无线连接（仅适用于 Android 10 及更低版本）

注意：此工作流程也适用于 Android 11（及更高版本），但需要注意的是，它也涉及通过物理 USB 进行的*初始*连接。

注意：以下说明不适用于运行 Android 10（API 级别 29）或更低版本的 Wear 设备。有关更多信息，请参阅调试 Wear OS 应用指南。

adb 通常通过 USB 与设备通信，但您也可以通过 Wi-Fi 使用adb。要连接运行 Android 10（API 级别 29）或更低版本的设备，请通过 USB 执行以下初始步骤

  1. 将您的 Android 设备和adb 主机计算机连接到同一个 Wi-Fi 网络。

    2. 注意：请注意，并非所有接入点都适合。您可能需要使用其防火墙配置正确以支持adb的接入点。

  2. 使用 USB 线缆将设备连接到主机计算机。
  3. 将目标设备设置为侦听端口 5555 上的 TCP/IP 连接
    adb tcpip 5555
  4. 从目标设备断开 USB 线缆。
  5. 查找 Android 设备的 IP 地址。例如，在 Nexus 设备上，您可以在设置>关于平板电脑（或关于手机）>状态>IP 地址中找到 IP 地址。
  6. 通过其 IP 地址连接到设备
    adb connect device_ip_address:5555
  7. 确认您的主机计算机已连接到目标设备
    $ adb devices
List of devices attached
device_ip_address:5555 device

您的设备现在已连接到adb。

如果与设备的adb连接断开

  • 确保您的主机仍连接到与 Android 设备相同的 Wi-Fi 网络。
  • 通过再次执行adb connect步骤重新连接。
  • 如果这不起作用，请重置您的adb主机
    adb kill-server

    然后从头开始。

查询设备

在发出adb命令之前，了解哪些设备实例连接到adb服务器非常有用。使用devices命令生成已连接设备的列表

  adb devices -l

作为响应，adb会为每个设备打印以下状态信息

  • 序列号：adb创建一个字符串，通过其端口号唯一标识设备。这是一个序列号示例：emulator-5554
  • 状态：设备的连接状态可以是以下之一
    • offline：设备未连接到adb或未响应。
    • device：设备已连接到adb服务器。请注意，此状态并不意味着 Android 系统已完全启动并运行，因为设备在系统仍在启动时连接到adb。启动后，这是设备的正常运行状态。
    • no device：没有设备连接。
  • 描述：如果您包含-l选项，则devices命令会告诉您设备是什么。当您连接多个设备时，此信息很有用，以便您可以区分它们。

以下示例显示了devices命令及其输出。有三个设备正在运行。列表中的前两行是模拟器，第三行是连接到计算机的硬件设备。

$ adb devices
List of devices attached
emulator-5556 device product:sdk_google_phone_x86_64 model:Android_SDK_built_for_x86_64 device:generic_x86_64
emulator-5554 device product:sdk_google_phone_x86 model:Android_SDK_built_for_x86 device:generic_x86
0a388e93      device usb:1-1 product:razor model:Nexus_7 device:flo

模拟器未列出

adb devices命令有一个极端情况的命令序列，会导致正在运行的模拟器未显示在adb devices输出中，即使模拟器在桌面上可见。当所有以下条件都为真时，就会发生这种情况

  • adb服务器未运行。

  • 您使用 emulator 命令以及 -port 或 -ports 选项，并指定 5554 到 5584 之间的奇数端口值。
  • 如果您选择的奇数端口空闲，则可以在指定的端口号上建立端口连接；如果该端口正忙，则模拟器会切换到另一个满足 2 中要求的端口。
  • 在启动模拟器后，启动 adb 服务器。

避免这种情况的一种方法是让模拟器自行选择端口，并且一次运行不超过 16 个模拟器。另一种方法是在使用 emulator 命令之前始终启动 adb 服务器，如下例所示。

示例 1：在以下命令序列中，adb devices 命令启动了 adb 服务器，但设备列表未显示。

停止 adb 服务器，并按所示顺序输入以下命令。对于 AVD 名称，请提供系统中有效的 AVD 名称。要获取 AVD 名称列表，请键入 emulator -list-avds。 emulator 命令位于 android_sdk/tools 目录中。

$ adb kill-server
$ emulator -avd Nexus_6_API_25 -port 5555
$ adb devices

List of devices attached
* daemon not running. starting it now on port 5037 *
* daemon started successfully *

示例 2：在以下命令序列中，adb devices 显示设备列表，因为 adb 服务器已首先启动。

要查看 adb devices 输出中的模拟器，请停止 adb 服务器，然后在使用 emulator 命令之后以及在使用 adb devices 命令之前重新启动它，如下所示

$ adb kill-server
$ emulator -avd Nexus_6_API_25 -port 5557
$ adb start-server
$ adb devices

List of devices attached
emulator-5557 device

有关模拟器命令行选项的更多信息，请参阅 命令行启动选项。

向特定设备发送命令

如果正在运行多个设备，则在发出 adb 命令时必须指定目标设备。要指定目标，请执行以下步骤

  1. 使用 devices 命令获取目标的序列号。
  2. 获得序列号后，使用 -s 选项以及 adb 命令来指定序列号。
    1. 如果您要发出许多 adb 命令，则可以将 $ANDROID_SERIAL 环境变量设置为包含序列号。
    2. 如果您同时使用 -s 和 $ANDROID_SERIAL，则 -s 会覆盖 $ANDROID_SERIAL。

在以下示例中，获取已连接设备的列表，然后使用其中一个设备的序列号在该设备上安装 helloWorld.apk

$ adb devices
List of devices attached
emulator-5554 device
emulator-5555 device
0.0.0.0:6520  device

# To install on emulator-5555
$ adb -s emulator-5555 install helloWorld.apk
# To install on 0.0.0.0:6520
$ adb -s 0.0.0.0:6520 install helloWorld.apk

注意：如果在有多个设备可用时未指定目标设备就发出命令，则 adb 会显示错误“adb: more than one device/emulator”。

如果有多个设备可用，但只有一个是模拟器，则使用 -e 选项向模拟器发送命令。如果有多个设备，但只有一个硬件设备连接，则使用 -d 选项向硬件设备发送命令。

安装应用

您可以使用 adb 通过 install 命令将 APK 安装到模拟器或连接的设备上。

adb install path_to_apk

在安装测试 APK 时，必须将 -t 选项与 install 命令一起使用。有关更多信息，请参阅 -t。

要安装多个 APK，请使用 install-multiple。如果您从 Play Console 下载了应用的特定设备的所有 APK，并希望将它们安装到模拟器或物理设备上，这将非常有用。

有关如何创建可在模拟器/设备实例上安装的 APK 文件的更多信息，请参阅 构建和运行您的应用。

注意：如果您使用的是 Android Studio，则无需直接使用 adb 将应用安装到模拟器或设备上。Android Studio 会为您处理应用的打包和安装。

设置端口转发

使用 forward 命令设置任意端口转发，这会将特定主机端口上的请求转发到设备上的另一个端口。以下示例设置了将主机端口 6100 转发到设备端口 7100

adb forward tcp:6100 tcp:7100

以下示例设置了将主机端口 6100 转发到 local:logd

adb forward tcp:6100 local:logd

如果您尝试确定发送到设备上特定端口的内容，这将很有用。所有接收到的数据都将写入系统日志守护程序并在设备日志中显示。

复制设备上的文件

使用 pull 和 push 命令复制设备上的文件。与仅将 APK 文件复制到特定位置的 install 命令不同，pull 和 push 命令允许您将任意目录和文件复制到设备中的任何位置。

要从设备复制文件或目录及其子目录，请执行以下操作

adb pull remote local

要到设备复制文件或目录及其子目录，请执行以下操作

adb push local remote

将 local 和 remote 替换为您开发机器（本地）和设备（远程）上目标文件/目录的路径。例如

adb push myfile.txt /sdcard/myfile.txt

停止 adb 服务器

在某些情况下，您可能需要终止 adb 服务器进程，然后重新启动它以解决问题。例如，如果 adb 对命令没有响应，则可能出现这种情况。

要停止 adb 服务器，请使用 adb kill-server 命令。然后，您可以通过发出任何其他 adb 命令来重新启动服务器。

发出 adb 命令

使用以下方法从开发机器上的命令行或从脚本中发出 adb 命令

adb [-d | -e | -s serial_number] command

如果只有一个模拟器正在运行或只有一个设备连接，则 adb 命令默认会发送到该设备。如果正在运行多个模拟器和/或连接了多个设备，则需要使用 -d、-e 或 -s 选项来指定命令应发送到的目标设备。

您可以使用以下命令查看所有受支持的 adb 命令的详细列表

adb --help

发出 shell 命令

您可以使用 shell 命令通过 adb 发出设备命令或启动交互式 shell。要发出单个命令，请像这样使用 shell 命令

adb [-d |-e | -s serial_number] shell shell_command

要在设备上启动交互式 shell，请像这样使用 shell 命令

adb [-d | -e | -s serial_number] shell

要退出交互式 shell，请按 Control+D 或键入 exit。

Android 提供了大多数常用的 Unix 命令行工具。要获取可用工具的列表，请使用以下命令

adb shell ls /system/bin

大多数命令都提供帮助信息，可以通过 --help 参数获取。许多 shell 命令由 toybox 提供。所有 toybox 命令通用的帮助信息可以通过 toybox --help 获取。

在 Android Platform Tools 23 及更高版本中，adb 处理参数的方式与 ssh(1) 命令相同。此更改修复了许多与 命令注入 相关的问题，并使得可以安全地执行包含 shell 元字符 的命令，例如 adb install Let\'sGo.apk。此更改意味着包含 shell 元字符的任何命令的解释也发生了变化。

例如，adb shell setprop key 'two words' 现在是错误的，因为本地 shell 会忽略引号，设备会看到 adb shell setprop key two words。要使命令正常工作，请使用双引号，一次用于本地 shell，一次用于远程 shell，就像使用 ssh(1) 一样。例如，adb shell setprop key "'two words'" 可以正常工作，因为本地 shell 会使用最外层的引号，而设备仍然会看到最内层的引号：setprop key 'two words'。转义也是一种选择，但通常使用双引号更容易。

另请参阅 Logcat 命令行工具，它对于监视系统日志很有用。

调用活动管理器

在 adb shell 中，您可以使用活动管理器 (am) 工具发出命令来执行各种系统操作，例如启动活动、强制停止进程、广播意图、修改设备屏幕属性等等。

在 shell 中，am 语法如下

am command

您也可以直接从 adb 发出活动管理器命令，而无需进入远程 shell。例如

adb shell am start -a android.intent.action.VIEW

表 1. 可用的活动管理器命令

命令 描述
start [options] intent 启动由 intent 指定的 Activity。

请参阅 意图参数规范。

选项包括：

  • -D：启用调试。
  • -W：等待启动完成。
  • --start-profiler file：启动分析器并将结果发送到 file。
  • -P file：类似于 --start-profiler，但分析在应用进入空闲状态时停止。
  • -R count：重复启动活动 count 次。在每次重复之前，将完成顶部活动。
  • -S：在启动活动之前强制停止目标应用。

  • --opengl-trace: 启用 OpenGL 函数跟踪。
  • --user user_id | current: 指定以哪个用户身份运行；如果未指定，则以当前用户身份运行。
startservice [options] intent 启动由 Service 指定的 intent。

请参阅 意图参数规范。

选项包括：

  • --user user_id | current: 指定以哪个用户身份运行。如果未指定，则以当前用户身份运行。
force-stop package 强制停止与 package 相关的所有内容。
kill [options] package 终止与 package 相关的所有进程。此命令仅终止可以安全终止且不会影响用户体验的进程。

选项包括：

  • --user user_id | all | current: 指定要终止哪个用户的进程。如果未指定，则终止所有用户的进程。
kill-all 终止所有后台进程。
broadcast [options] intent 发出广播意图。

请参阅 意图参数规范。

选项包括：

  • [--user user_id | all | current]: 指定要发送到的用户。如果未指定，则发送到所有用户。
instrument [options] component 使用 Instrumentation 实例开始监控。通常，目标 component 的形式为 test_package/runner_class。

选项包括：

  • -r: 打印原始结果（否则解码 report_key_streamresult）。与 [-e perf true] 一起使用以生成性能测量的原始输出。
  • -e name value: 将参数 name 设置为 value。对于测试运行器，常见形式为 -e testrunner_flag value[,value...]。
  • -p file: 将性能分析数据写入 file。
  • -w: 在返回之前等待检测完成。测试运行器需要此选项。
  • --no-window-animation: 运行时关闭窗口动画。
  • --user user_id | current: 指定检测在哪个用户中运行。如果未指定，则在当前用户中运行。
profile start process file 在 process 上启动性能分析器，并将结果写入 file。
profile stop process 停止 process 上的性能分析器。
dumpheap [options] process file 转储 process 的堆，写入 file。

选项包括：

  • --user [user_id | current]: 提供进程名称时，指定要转储的进程的用户。如果未指定，则使用当前用户。
  • -b [| png | jpg | webp]: 转储图形内存中的位图（API 级别 35 及更高版本）。可以选择指定要转储的格式（默认为 PNG）。
  • -n: 转储本机堆而不是托管堆。
set-debug-app [options] package 将应用 package 设置为调试。

选项包括：

  • -w: 应用启动时等待调试器。
  • --persistent: 保留此值。
clear-debug-app 清除之前使用 set-debug-app 设置的调试包。
monitor [options] 开始监控崩溃或 ANR。

选项包括：

  • --gdb: 在崩溃/ANR 时在给定端口上启动 gdbserv。
screen-compat {on | off} package 控制 package 的 屏幕兼容性 模式。
display-size [reset | widthxheight] 覆盖设备显示尺寸。此命令可通过使用大屏幕设备模拟小屏幕分辨率来测试不同屏幕尺寸上的应用，反之亦然。

示例
am display-size 1280x800

display-density dpi 覆盖设备显示密度。此命令可通过使用低密度屏幕模拟高密度屏幕环境来测试不同屏幕密度上的应用，反之亦然。

示例
am display-density 480

to-uri intent 将给定的意图规范打印为 URI。

请参阅 意图参数规范。
to-intent-uri intent 将给定的意图规范打印为 intent: URI。

请参阅 意图参数规范。

意图参数规范

对于使用 intent 参数的活动管理器命令，可以使用以下选项指定意图

调用包管理器 (pm)

在 adb shell 中，您可以使用包管理器 (pm) 工具发出命令，以对设备上安装的应用包执行操作和查询。

在 shell 中，pm 语法为

pm command

您也可以直接从 adb 发出包管理器命令，而无需进入远程 shell。例如

adb shell pm uninstall com.example.MyApp

表 2. 可用的包管理器命令

命令 描述
list packages [options] filter 打印所有包，或者仅打印包名包含 filter 中文本的包。

选项

  • -f：查看关联文件。
  • -d：过滤以仅显示禁用的包。
  • -e：过滤以仅显示启用的包。
  • -s：过滤以仅显示系统包。
  • -3：过滤以仅显示第三方包。
  • -i：查看包的安装程序。
  • -u：包含已卸载的包。
  • --user user_id：要查询的用户空间。
list permission-groups 打印所有已知的权限组。
list permissions [options] group 打印所有已知的权限，或者仅打印 group 中的权限。

选项

  • -g：按组组织。
  • -f：打印所有信息。
  • -s：简短摘要。
  • -d：仅列出危险权限。
  • -u：仅列出用户将看到的权限。
list instrumentation [options] 列出所有测试包。

选项

  • -f：列出测试包的 APK 文件。
  • target_package：仅列出此应用的测试包。
list features 打印系统的所有功能。
list libraries 打印当前设备支持的所有库。
list users 打印系统上的所有用户。
path package 打印给定 package 的 APK 的路径。
install [options] path 将由 path 指定的包安装到系统中。

选项

  • -r：重新安装现有应用，保留其数据。
  • -t：允许安装测试 APK。当您仅运行或调试应用或使用 Android Studio 构建 > 构建 APK 命令时，Gradle 会生成一个测试 APK。如果使用开发者预览版 SDK 构建了 APK，则如果要安装测试 APK，则必须将 -t 选项 与 install 命令一起使用。
  • -i installer_package_name：指定安装程序包名。
  • --install-location location：使用以下值之一设置安装位置
    • 0：使用默认安装位置。
    • 1：安装在内部设备存储上。
    • 2：安装在外部媒体上。
  • -f：将包安装在内部系统内存上。
  • -d：允许版本代码降级。
  • -g：授予应用清单中列出的所有权限。
  • --fastdeploy：通过仅更新 APK 中已更改的部分来快速更新已安装的包。
  • --incremental：安装足够的 APK 以启动应用，同时在后台流式传输其余数据。要使用此功能，必须对 APK 进行签名，创建 APK 签名方案 v4 文件 并将其放置在与 APK 相同的目录中。此功能仅在某些设备上受支持。此选项强制 adb 使用此功能，或者如果不受支持，则失败，并提供有关失败原因的详细信息。附加 --wait 选项以等待 APK 完全安装，然后再授予对 APK 的访问权限。

    --no-incremental 阻止 adb 使用此功能。
uninstall [options] package 从系统中删除包。

选项

  • -k：删除包后保留数据和缓存目录。
  • --user user_id：指定要为其删除包的用户。
  • --versionCode version_code：仅在应用具有给定版本代码时才卸载。
clear package 删除与包关联的所有数据。
enable package_or_component 启用给定的包或组件（写为“package/class”）。
disable package_or_component 禁用给定的包或组件（写为“package/class”）。
disable-user [options] package_or_component

选项

  • --user user_id：要禁用的用户。
grant package_name permission 授予应用权限。在运行 Android 6.0（API 级别 23）或更高版本的设备上，权限可以是应用清单中声明的任何权限。在运行 Android 5.1（API 级别 22）或更低版本的设备上，必须是应用定义的可选权限。
revoke package_name permission 撤销应用的权限。在运行 Android 6.0（API 级别 23）或更高版本的设备上，权限可以是应用清单中声明的任何权限。在运行 Android 5.1（API 级别 22）或更低版本的设备上，必须是应用定义的可选权限。
set-install-location location 更改默认安装位置。位置值
  • 0：自动：让系统决定最佳位置。
  • 1：内部：安装在内部设备存储上。
  • 2：外部：安装在外部媒体上。

注意：这仅用于调试。使用此功能可能会导致应用崩溃和其他不良行为。
get-install-location 返回当前安装位置。返回值
  • 0 [auto]：让系统决定最佳位置
  • 1 [internal]：安装在内部设备存储上
  • 2 [external]：安装在外部媒体上
set-permission-enforced permission [true | false] 指定是否应强制执行给定权限。
trim-caches desired_free_space 修剪缓存文件以达到给定的可用空间。
create-user user_name 使用给定的 user_name 创建一个新用户，并打印用户的新的用户标识符。
remove-user user_id 删除具有给定 user_id 的用户，并删除与该用户关联的所有数据
get-max-users 打印设备支持的最大用户数。
get-app-links [options] [package]

打印给定 package 的域验证状态，或者如果没有指定，则打印所有包的域验证状态。状态代码定义如下

  • none：尚未为此域记录任何内容
  • verified：域已成功验证
  • approved：强制批准，通常通过 shell
  • denied：强制拒绝，通常通过 shell
  • migrated：从旧响应中保留的验证
  • restored：从用户数据恢复中保留的验证
  • legacy_failure：被旧验证程序拒绝，原因未知
  • system_configured：由设备配置自动批准
  • >= 1024：自定义错误代码，特定于设备验证程序

选项包括：

  • --user user_id：包含用户选择。包括所有域，而不仅仅是 autoVerify 域。
reset-app-links [options] [package]

重置给定包的域验证状态，或者如果没有指定，则重置所有包的域验证状态。

  • package：要重置的包，或“all”以重置所有包

选项包括：

  • --user user_id：包含用户选择。包括所有域，而不仅仅是 autoVerify 域。
verify-app-links [--re-verify] [package]

为给定的 package 广播验证请求，或者如果没有指定，则为所有包广播验证请求。仅在包先前未记录响应时发送。

  • --re-verify：即使包已记录响应也发送
set-app-links [--package package] state domains

手动设置包的域的状态。域必须由包声明为 autoVerify 才能使此操作生效。此命令不会报告无法应用的域的错误。

  • --package package：要设置的包，或“all”以设置所有包
  • state：要将域设置为的代码。有效值为
    • STATE_NO_RESPONSE (0)：重置为好像从未记录过响应。
    • STATE_SUCCESS (1)：将域视为已由域验证代理成功验证。请注意，域验证代理可以覆盖此设置。
    • STATE_APPROVED (2)：将域视为始终已批准，阻止域验证代理更改它。
    • STATE_DENIED (3)：将域视为始终被拒绝，阻止域验证代理更改它。
  • domains：要更改的域的空格分隔列表，或“all”以更改每个域。
set-app-links-user-selection --user user_id [--package package] enabled domains

手动设置包的主机用户选择的狀態。此操作需要包声明该域才能生效。此命令不会报告无法应用的域的失败。

  • --user user_id：要更改其选择的用戶
  • --package package：要设置的包
  • enabled：是否批准域
  • domains：要更改的域的空格分隔列表，或“all”以更改每个域
set-app-links-user-selection --user user_id [--package package] enabled domains

手动设置包的主机用户选择的狀態。此操作需要包声明该域才能生效。此命令不会报告无法应用的域的失败。

  • --user user_id：要更改其选择的用戶
  • --package package：要设置的包
  • enabled：是否批准域
  • domains：要更改的域的空格分隔列表，或“all”以更改每个域
set-app-links-allowed --user user_id [--package package] allowed

切换包的自动验证链接处理设置。

  • --user user_id：要更改其选择的用戶
  • --package package：要设置的包，或“all”以设置所有包；如果未指定包，则会重置包
  • allowed：true 表示允许包打开自动验证链接，false 表示禁用
get-app-link-owners --user user_id [--package package] domains

按从低到高的优先级顺序打印给定用户的特定域的所有者。

  • --user user_id：要查询的用戶
  • --package package：可选地也打印包声明的所有 Web 域，或“all”以打印所有包
  • domains：要查询的域的空格分隔列表

调用设备策略管理器（dpm）

为了帮助您开发和测试设备管理应用，向设备策略管理器（dpm）工具发出命令。使用该工具控制活动的管理员应用或更改设备上策略的狀態数据。

在 Shell 中，dpm语法如下

dpm command

您还可以直接从 adb发出设备策略管理器命令，而无需进入远程 Shell

adb shell dpm command

表 3. 可用的设备策略管理器命令

命令 描述
set-active-admin [options] component 将 component 设置为活动管理员。

选项包括：

  • --user user_id：指定目标用户。您还可以传递 --user current 以选择当前用户。
set-profile-owner [options] component 将 component 设置为活动管理员，并将其包设置为现有用户的配置文件所有者。

选项包括：

  • --user user_id：指定目标用户。您还可以传递 --user current 以选择当前用户。
  • --name name：指定易于理解的组织名称。
set-device-owner [options] component 将 component 设置为活动管理员，并将其包设置为设备所有者。

选项包括：

  • --user user_id：指定目标用户。您还可以传递 --user current 以选择当前用户。
  • --name name：指定易于理解的组织名称。
remove-active-admin [options] component 禁用活动管理员。应用必须在清单中声明 android:testOnly。此命令还会删除设备和配置文件所有者。

选项包括：

  • --user user_id：指定目标用户。您还可以传递 --user current 以选择当前用户。
clear-freeze-period-record 清除设备先前为系统 OTA 更新设置的冻结时段记录。这有助于在开发管理冻结时段的应用时避免设备计划限制。请参阅管理系统更新。

在运行 Android 9.0（API 级别 28）或更高版本的设备上受支持。
force-network-logs 强制系统使任何现有的网络日志可供 DPC 检索。如果有连接或 DNS 日志可用，则 DPC 会收到 onNetworkLogsAvailable() 回调。请参阅网络活动日志记录。

此命令受速率限制。在运行 Android 9.0（API 级别 28）或更高版本的设备上受支持。
force-security-logs 强制系统使任何现有的安全日志可供 DPC 使用。如果有日志可用，则 DPC 会收到 onSecurityLogsAvailable() 回调。请参阅记录企业设备活动。

此命令受速率限制。在运行 Android 9.0（API 级别 28）或更高版本的设备上受支持。

截取屏幕截图

screencap 命令是一个用于截取设备显示屏截图的 Shell 实用程序。

在 Shell 中，screencap 语法如下

screencap filename

要从命令行使用 screencap，请输入以下内容

adb shell screencap /sdcard/screen.png

这是一个屏幕截图会话示例，使用 adb shell 截取屏幕截图，并使用 pull 命令从设备下载文件

$ adb shell
shell@ $ screencap /sdcard/screen.png
shell@ $ exit
$ adb pull /sdcard/screen.png

录制视频

screenrecord 命令是一个用于录制运行 Android 4.4（API 级别 19）或更高版本的设备显示屏的 Shell 实用程序。该实用程序将屏幕活动录制到 MPEG-4 文件中。您可以使用此文件创建宣传或培训视频，或用于调试和测试。

在 Shell 中，使用以下语法

screenrecord [options] filename

要从命令行使用 screenrecord，请输入以下内容

adb shell screenrecord /sdcard/demo.mp4

按 Control+C 停止屏幕录制。否则，录制将在三分钟或 --time-limit 设置的时间限制后自动停止。

要开始录制设备屏幕，请运行 screenrecord 命令录制视频。然后，运行 pull 命令将视频从设备下载到主机计算机。这是一个录制会话示例

$ adb shell
shell@ $ screenrecord --verbose /sdcard/demo.mp4
(press Control + C to stop)
shell@ $ exit
$ adb pull /sdcard/demo.mp4

screenrecord 实用程序可以以您请求的任何受支持的分辨率和比特率进行录制，同时保留设备显示屏的纵横比。默认情况下，该实用程序以本机显示分辨率和方向进行录制，最长时长为三分钟。

screenrecord 实用程序的限制

  • 视频文件中未录制音频。
  • 运行 Wear OS 的设备无法录制视频。
  • 某些设备可能无法以其本机显示分辨率进行录制。如果您遇到屏幕录制问题，请尝试使用较低的屏幕分辨率。
  • 录制期间不支持屏幕旋转。如果屏幕在录制过程中旋转，则录制中会截断部分屏幕。

表 4. screenrecord 选项

选项 描述
--help 显示命令语法和选项
--size widthxheight 设置视频大小：1280x720。默认值为设备的本机显示分辨率（如果支持），否则为 1280x720。为了获得最佳效果，请使用设备的 Advanced Video Coding (AVC) 编码器支持的大小。
--bit-rate rate 设置视频的视频比特率，单位为兆比特每秒。默认值为 20Mbps。您可以提高比特率以提高视频质量，但这样做会导致电影文件更大。以下示例将录制比特率设置为 6Mbps
screenrecord --bit-rate 6000000 /sdcard/demo.mp4
--time-limit time 设置最大录制时间，单位为秒。默认值和最大值为 180（3 分钟）。
--rotate 将输出旋转 90 度。此功能处于实验阶段。
--verbose 在命令行屏幕上显示日志信息。如果您未设置此选项，则实用程序在运行时不会显示任何信息。

读取应用的 ART 配置文件

从 Android 7.0（API 级别 24）开始，Android 运行时 (ART) 会为已安装的应用收集执行配置文件，这些配置文件用于优化应用性能。检查收集的配置文件以了解哪些方法经常执行以及在应用启动期间使用了哪些类。

注意： 只有在您对文件系统具有 root 访问权限（例如，在模拟器上）时，才能检索执行配置文件文件名。

要生成配置文件信息的文本形式，请使用以下命令

adb shell cmd package dump-profiles package

要检索生成的文件，请使用

adb pull /data/misc/profman/package.prof.txt

重置测试设备

如果您在多个测试设备上测试应用，则在测试之间重置设备可能很有用，例如，删除用户数据并重置测试环境。您可以使用 testharness adb shell 命令对运行 Android 10（API 级别 29）或更高版本的测试设备执行恢复出厂设置，如下所示

adb shell cmd testharness enable

使用 testharness 恢复设备时，设备会自动在持久位置备份允许通过当前工作站进行调试的 RSA 密钥。也就是说，在设备重置后，工作站可以继续调试并向设备发出 adb 命令，而无需手动注册新密钥。

此外，为了使继续测试应用变得更容易和更安全，使用 testharness 恢复设备还会更改以下设备设置

  • 设备会设置某些系统设置，以便不会出现初始设备设置向导。也就是说，设备进入一种状态，您可以从中快速安装、调试和测试应用。
  • 设置
    • 禁用锁定屏幕。
    • 禁用紧急警报。
    • 禁用帐户的自动同步。
    • 禁用自动系统更新。
  • 其他
    • 禁用预装的安全应用。

如果您的应用需要检测和适应 testharness 命令的默认设置，请使用 ActivityManager.isRunningInUserTestHarness()。

sqlite

sqlite3 用于启动 sqlite 命令行程序，以便检查 SQLite 数据库。它包含诸如 .dump（用于打印表的內容）和 .schema（用于打印现有表的 SQL CREATE 语句）等命令。您还可以从命令行执行 SQLite 命令，如所示

$ adb -s emulator-5554 shell
$ sqlite3 /data/data/com.example.app/databases/rssitems.db
SQLite version 3.3.12
Enter ".help" for instructions

注意： 只有在您拥有文件系统的 root 访问权限（例如，在模拟器上）时，才能访问 SQLite 数据库。

有关更多信息，请参阅 sqlite3 命令行文档。

adb USB 后端

adb 服务器可以通过两个后端与 USB 堆栈进行交互。它可以使用操作系统的原生后端（Windows、Linux 或 macOS），也可以使用 libusb 后端。某些功能（例如 attach、detach 和 USB 速度检测）仅在使用 libusb 后端时可用。

您可以使用 ADB_LIBUSB 环境变量来选择后端。如果未设置，adb 将使用其默认后端。默认行为在不同操作系统之间有所不同。从 ADB v34 开始，在除 Windows 之外的所有操作系统上默认使用 liubusb 后端，在 Windows 上默认使用原生后端。如果设置了 ADB_LIBUSB，则它将决定使用原生后端还是 libusb。有关 adb 环境变量的更多信息，请参阅 adb 手册页。

adb mDNS 后端

ADB 可以使用多播 DNS 协议自动连接服务器和设备。ADB 服务器附带两个后端：Bonjour（Apple 的 mdnsResponder）和 Openscreen。

Bonjour 后端需要在主机上运行一个守护进程。在 macOS 上，Apple 的内置守护进程始终处于运行状态，但在 Windows 和 Linux 上，用户必须确保 mdnsd 守护进程已启动并正在运行。如果命令 adb mdns check 返回错误，则可能是 ADB 正在使用 Bonjour 后端，但没有运行 Bonjour 守护进程。

Openscreen 后端不需要在机器上运行守护进程。macOS 上对 Openscreen 后端的支持从 ADB v35 开始。Windows 和 Linux 从 ADB v34 开始支持。

默认情况下，ADB 使用 Bonjour 后端。可以使用环境变量 ADB_MDNS_OPENSCREEN（设置为 1 或 0）更改此行为。有关详细信息，请参阅 ADB 手册页。