Android 调试桥 (adb)

Android 调试桥 (adb) 是一个多功能命令行工具，可让您与设备通信。adb 命令可执行各种设备操作，例如安装和调试应用。adb 提供对 Unix 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 调试桥 (adb) 从工作站无线部署和调试您的应用。例如，您可以将可调试应用部署到多个远程设备，而无需物理连接设备通过 USB。这消除了处理常见 USB 连接问题的需要，例如驱动程序安装。

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

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

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

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

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

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

  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. 使用二维码或配对码配对设备的弹出窗口。

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

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

    1. 要使用二维码配对设备，请选择使用二维码配对设备并扫描从图 2 所示的通过 Wi-Fi 配对设备弹出窗口中获得的二维码。

    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 网络）可能会阻止 p2p 连接，从而无法通过 Wi-Fi 连接。尝试使用有线连接或另一个（非公司）Wi-Fi 网络。在tcp/ip上使用 adb connect ip:port进行无线连接（在初始 USB 连接之后）是另一种选择，以防万一需要使用非公司网络。

  • adb over 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. 获得序列号后，使用 adb 命令的 -s 选项指定序列号。
    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 管理中心下载了应用的所有 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 --help 可提供适用于所有 toybox 命令的通用帮助。

从 Android 平台工具 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 manager (am) 工具发出命令，以执行各种系统操作，例如启动 activity、强制停止进程、广播 intent、修改设备屏幕属性等等。

在 shell 中，am 语法为

am command

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

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

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

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

请参阅意图参数规范。

选项是

  • -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。

请参阅意图参数规范。

选项是

  • --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：等待 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。将创建一个名为 dumpbitmaps-<time>.zip 的 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 将给定意图规范打印为 URI。

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

请参阅意图参数规范。

意图参数规范

对于接受 intent 参数的 activity manager 命令，您可以使用以下选项指定意图

当参数未由上述选项之一限定时，您可以直接指定 URI、包名和组件名。如果参数包含“:”（冒号），则工具假定该参数是 URI。如果参数包含“/”（斜杠），则工具假定该参数是组件名；否则，它假定该参数是包名。

调用软件包管理器 (pm)

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

pm command

在 shell 中，pm 语法为

adb shell pm uninstall com.example.MyApp

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

命令 描述
表 2. 可用的软件包管理器命令 list packages [options] filter

打印所有软件包，可选地只打印其软件包名称包含 filter 中文本的软件包。

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

打印所有软件包，可选地只打印其软件包名称包含 filter 中文本的软件包。

  • 打印所有已知权限，可选地只打印 group 中的权限。
  • -g：按组组织。
  • -f：打印所有信息。
  • -s：简短摘要。
  • -d：只列出危险权限。
-u：只列出用户会看到的权限。 list instrumentation [options]

打印所有软件包，可选地只打印其软件包名称包含 filter 中文本的软件包。

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

打印所有软件包，可选地只打印其软件包名称包含 filter 中文本的软件包。

  • 将由 path 指定的软件包安装到系统。
  • -r：重新安装现有应用，保留其数据。
  • -t：允许安装测试 APK。当您只运行或调试了应用，或者使用了 Android Studio 的构建 > 构建 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

打印所有软件包，可选地只打印其软件包名称包含 filter 中文本的软件包。

  • 从系统中移除软件包。
  • -k：软件包移除后保留数据和缓存目录。
  • --user user_id：指定为哪个用户移除软件包。默认情况下，软件包会为设备上的所有用户移除。
--versionCode version_code：仅当应用具有给定版本代码时才卸载。 clear package
删除与软件包相关的所有数据。 enable package_or_component
启用给定软件包或组件（写为“package/class”）。 disable package_or_component
禁用给定软件包或组件（写为“package/class”）。

打印所有软件包，可选地只打印其软件包名称包含 filter 中文本的软件包。

  • 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]

  • 重置给定软件包的域名验证状态，如果未指定则重置所有软件包的状态。

选项是

  • >= 1024：自定义错误代码，特定于设备验证器
package：要重置的包，或“all”以重置所有包

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)：将域视为始终拒绝，阻止域验证代理更改它。
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 命令是一个 Shell 实用程序，用于录制运行 Android 4.4 (API 级别 19) 及更高版本的设备的显示屏。该实用程序会将屏幕活动录制到 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 选项

打印所有软件包，可选地只打印其软件包名称包含 filter 中文本的软件包。 描述
--help 显示命令语法和选项
--size widthxheight 设置视频尺寸：1280x720。默认值为设备的原始显示分辨率（如果支持），否则为 1280x720。为获得最佳效果，请使用设备的高级视频编码 (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 Runtime (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 可以使用多播 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 手册页。

adb 突发模式（从 ADB 36.0.0 开始）

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

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

  • 将环境变量 ADB_DELAYED_ACK 设置为 1。
  • 在 Android Studio 中，转到 File（在 macOS 上是 Android Studio）> Settings > Build, Execution, Deployment > Debugger 中的调试器设置，然后将 ADB Server Burst Mode 设置为 Enabled。