Android Debug Bridge (adb)

Android Debug Bridge (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 来验证设备是否已连接。如果已连接，您将看到设备名称列为“device”。

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

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

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

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

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

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

注意：您只需将设备与工作站配对一次。设备将保持与工作站的配对状态，直到您明确取消配对或在设备上撤销 adb 调试授权。当设备和工作站处于同一网络时，它们会自动连接。

  1. 启用开发者选项。

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

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

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

    4. Screenshot of a Google Pixel phone showing the Wireless debugging systems setting.
    图 2. Google Pixel 手机上的“无线调试”设置。

    注意：Android Studio 用户可以使用二维码配对设备，选择“使用二维码配对设备”，然后扫描在 Android Studio 的通过 Wi-Fi 配对设备对话框中获取的二维码。

  4. 在设备上，选择“使用配对码配对”，并记下设备上显示的 IP 地址、端口号和配对码。

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

  6. 在工作站的终端上，运行 adb pair ipaddr:port。使用上一步中的 IP 地址和端口号。

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

    Screenshot of pairing on the command line.
    图 3. 消息显示您的设备已成功配对。

  8. 设备配对后，请验证设备是否已连接。您现在可以像使用 USB 连接一样无线使用您的设备了。

    要取消与工作站的配对，请导航至设备上的“无线调试”。点击“已配对设备”下的工作站名称，然后选择“忘记”。或者，您可以点击设备“设置”页面上的“撤销 adb 调试授权”，以取消与工作站及所有之前配对过的其他工作站的配对。

  9. 如果您想快速开启和关闭无线调试，可以利用“开发者选项”>“快捷设置开发者磁贴”中的“无线调试”快捷设置开发者磁贴。

    Screenshot of Quick settings developer tiles from a Google Pixel phone.
    图 4. “快捷设置开发者磁贴”设置让您可以快速开启和关闭无线调试。

解决无线连接问题

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

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

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

检查您的工作站上的 adb 设置是否正确

要验证工作站上的 ADB 设置是否正确，请在工作站上打开终端并输入 adb server-status。验证输出是否显示以下内容

  • version: "37.0.0" 或更高版本： 如果不是这种情况，请下载最新版本的 SDK 平台工具。
  • mdns_enabled: true：如果此项设置为 false，则 adb 将无法自动发现网络上的设备。要解决此问题，必须将 ADB_MDNS 环境变量设置为 1，然后通过运行 adb kill-server 和 adb start-server 重启 adb 服务器。
  • mdns_backend: LIBADBMDNS：如果不是这种情况，则 adb 正在使用过时的库来自动发现网络上的设备。要解决此问题，必须将 ADB_MDNS_OPENSCREEN 环境变量设置为 0，然后通过运行 adb kill-server 和 adb start-server 重启 adb 服务器。

检查您的网络是否支持 mDNS

adb 依赖 mDNS 自动发现并连接到已配对的设备。要检查您的网络是否支持 mDNS，请执行以下操作

  1. 在设备上，启用无线调试（如通过 Wi-Fi 连接设备一节所述）。

  2. 在工作站上，打开终端并输入 adb mdns track-services --proto-text。

  3. 验证输出不为空，并且包含带有设备 IP 地址和端口号的 tls 服务。如果输出为空，则说明您的网络不支持 mDNS。示例输出

    tls {
  service {
    instance: "adb-35121FDJH000R8-xyMD0H"
    service: "_adb-tls-connect._tcp"
    ipv4: "192.168.84.23"
    ipv6: "fe80:0:0:0:fc7a:299d:8d38:6c1c"
    port: 37895
    product_model: "Pixel 8"
    build_version_sdk_full: "37.0"
    given_name: "sherifeid Pixel"
    serial: "35121FDJH000R8"
    mdns_service_version: "2.0"
    hostname: "Android_CXUKYJY1.local"
  }
}

检查您的设备是否支持 ADB Wi-Fi 2.0

注意：Android 17 及更高版本支持 ADB Wi-Fi 2.0。

要检查您的设备是否支持 ADB Wi-Fi 2.0，请执行以下操作

  1. 在设备上，启用无线调试（如通过 Wi-Fi 连接设备一节所述）。

  2. 在工作站上，打开终端并输入 adb mdns track-services --proto-text。

  3. 验证输出包含 mdns_service_version: "2.0" 或更高版本。如果不是这种情况，则您的设备运行的不是 Android 17 或更高版本，且不支持 ADB Wi-Fi 2.0。要更新到 Android 17 或更高版本，请检查您的设备是否有待处理的系统更新。检查并更新您的 Android 版本。

报告新问题

如果您在无线连接设备时仍然遇到问题，您可以报告一个新问题。请确保在报告中提供以下信息

  • 您的设备日志：重现问题并附上设备日志
  • 来自工作站 adb 的日志
    1. 设置环境变量 ADB_TRACE=all。
    2. 重启 adb 服务器，方法是运行 adb kill-server，然后运行 adb start-server。
    3. 重现问题。
    4. 找到日志文件：运行 adb server-status 并附上输出 log_absolute_path 中引用的日志文件。

初始 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 时，必须在 install 命令中使用 -t 选项。有关更多信息，请参阅 -t。

要安装多个 APK，请使用 install-multiple。如果您从 Play 管理中心为您的应用下载了特定设备的所有 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 命令行工具，它对于监控系统日志很有用。

调用 Activity 管理器

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

在 shell 中时，am 语法为

am command

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

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

表 1. 可用的 Activity 管理器命令

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

请参阅Intent 参数规范。

选项包括

  • -D：启用调试。
  • -W：等待启动完成。
  • --start-profiler file：启动性能分析器并将结果发送到 file。
  • -P file：类似于 --start-profiler，但当应用进入空闲状态时分析停止。
  • -R count：重复启动 Activity count 次。在每次重复之前，顶层 Activity 将被结束。
  • -S：在启动 Activity 之前强制停止目标应用。
  • --opengl-trace：启用 OpenGL 函数跟踪。
  • --user user_id | current：指定要以哪个用户身份运行；如果未指定，则以当前用户身份运行。
startservice [options] intent 启动由 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 发送广播 Intent。

请参阅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：等待 instrumentation 完成再返回。测试运行程序必需。
  • --no-window-animation：运行期间关闭窗口动画。
  • --user user_id | current：指定 instrumentation 在哪个用户中运行。如果未指定，则在当前用户中运行。
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：转储原生堆而不是托管堆。
dumpbitmaps [options] [-p process] 从 process 转储位图信息（API 级别 36 及以上）。选项包括

  • -d|--dump [format]：以指定的 format 转储位图内容，格式可以是 png、jpg 或 webp，如果不指定，默认为 png。将创建一个包含位图的 zip 文件 dumpbitmaps-<time>.zip。
  • -p process：从 process 转储位图，可指定多个 -p process。
如果未指定 process，将转储所有进程的位图。
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 将给定的 Intent 规范打印为 URI。请参阅Intent 参数规范。
to-intent-uri intent 将给定的 Intent 规范打印为 intent: URI。请参阅Intent 参数规范。

Intent 参数规范

对于接受 intent 参数的 Activity 管理器命令，您可以使用以下选项指定 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 Build > Build APK 命令时，Gradle 会生成测试 APK。如果 APK 是使用开发者预览版 SDK 构建的，在安装测试 APK 时，您必须在 install 命令中包含 -t 选项。
  • -i installer_package_name：指定安装程序包名。
  • --user user_id：指定要为其安装包的用户。默认情况下，该包会为设备上存在的所有用户安装。
  • --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-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

    或者，如果您省略文件名，screencap 会将图像写入标准输出。结合使用 -p 选项指定 PNG 格式，您可以将设备截图直接流式传输到本地计算机上的文件中。

    以下是一个通过单条命令截取屏幕截图并将其保存在本地的示例

    # use 'exec-out' instead of 'shell' to get raw data
$ adb exec-out screencap -p > 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。为获得最佳效果，请使用设备的高级视频编码 (AVC) 编码器支持的大小。
    --bit-rate rate 设置视频比特率（单位为 Mbps）。默认值为 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 外，所有操作系统默认均使用 libusb 后端；Windows 默认使用原生后端。如果设置了 ADB_LIBUSB，它将决定使用原生后端还是 libusb。有关 adb 环境变量的更多信息，请参阅 adb 手册页。

    adb mDNS 后端

    ADB 使用 mDNS（多播 DNS）协议自动连接服务器和设备以进行无线调试。截至 ADB v37，ADB 服务器附带两个 mDNS 后端：libadbmdns 和 openscreen。

    默认且推荐的后端是 libadbmdns。此行为可以使用环境变量 ADB_MDNS_OPENSCREEN（设置为 1 或 0）进行更改。macOS 对 Openscreen 后端的支持始于 ADB v35。Windows 和 Linux 的支持始于 ADB v34。

    adb 突发模式 (Burst Mode)（始于 ADB 36.0.0）

    突发模式是一项实验性功能，允许 ADB 在设备响应前一个数据包之前继续向设备发送数据包。这极大地提高了 ADB 在传输大文件时的吞吐量，并减少了调试时的延迟。

    突发模式默认处于禁用状态。若要启用此功能，请执行以下任一操作

    • 将环境变量 ADB_BURST_MODE 设置为 1。
    • 在 Android Studio 中，前往调试器设置：File（macOS 上为 Android Studio）> Settings > Build, Execution, Deployment > Debugger，并将 ADB Server Burst Mode 设置为 Enabled。