Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

Android 调试桥 (adb)

Android 调试桥 (adb) 是一种功能多样的命令行工具,可让您与设备进行通信。adb 命令便于执行各种设备操作(例如安装和调试应用),并提供对 Unix shell(可用来在设备上运行各种命令)的访问权限。它是一种客户端-服务器程序,包括以下三个组件:

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

adb 包含在 Android SDK 平台工具软件包中。您可以使用 SDK 管理器下载此软件包,管理器会将此软件包安装在 android_sdk/platform-tools/。或者,如果您需要独立的 Android SDK 平台工具软件包,可以点击此处进行下载

要了解如何连接设备以进行 adb 通信,包括如何使用 Connection Assistant 对常见问题进行排查,请参阅在硬件设备上运行应用

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 及更高版本的设备上,“开发者选项”屏幕默认情况下处于隐藏状态。如需将其显示出来,请依次转到设置 > 关于手机,然后点按版本号七次。返回上一屏幕,在底部可以找到开发者选项

在某些设备上,“开发者选项”屏幕所在的位置或命名方式可能有所不同。

现在,您已经可以通过 USB 连接设备。您可以从 android_sdk/platform-tools/ 目录执行 adb devices,验证设备是否已连接。如果已连接,您将看到设备名称以“设备”形式列出。

注意:当您连接搭载 Android 4.2.2 或更高版本的设备时,系统会显示一个对话框,询问您是否接受允许通过此计算机进行调试的 RSA 密钥。这种安全机制可以保护用户设备,因为它可以确保只有在您能够解锁设备并确认对话框的情况下才能执行 USB 调试和其他 adb 命令。

要详细了解如何通过 USB 连接到设备,请参阅在硬件设备上运行应用

通过 WLAN 连接到设备

一般情况下,adb 通过 USB 与设备进行通信,但您也可以在通过 USB 完成一些初始设置后通过 WLAN 使用 adb,如下所述。如果您开发的是 Wear OS 应用,则应改为参阅调试 Wear OS 应用指南,其中提供了有关如何通过 WLAN 和蓝牙使用 adb 的特别说明。

  1. 将 Android 设备和 adb 主机连接到这两者都可以访问的同一 WLAN 网络。请注意,并非所有接入点都适用;您可能需要使用防火墙已正确配置为支持 adb 的接入点。
  2. 如果您要连接到 Wear OS 设备,请关闭与该设备配对的手机上的蓝牙。
  3. 使用 USB 数据线将设备连接到主机。
  4. 设置目标设备以监听端口 5555 上的 TCP/IP 连接。
        adb tcpip 5555
        
  5. 拔掉连接目标设备的 USB 数据线。
  6. 找到 Android 设备的 IP 地址。例如,对于 Nexus 设备,您可以在设置 > 关于平板电脑(或关于手机)> 状态 > IP 地址下找到 IP 地址。或者,在 Wear OS 设备上,您可以在设置 > WLAN 设置 > 高级 > IP 地址下找到 IP 地址。
  7. 通过 IP 地址连接到设备。
        adb connect device_ip_address
        
  8. 确认主机已连接到目标设备:
        $ adb devices
        List of devices attached
        device_ip_address:5555 device
        

现在,您可以开始操作了!

如果 adb 连接断开:

  1. 确保主机仍与 Android 设备连接到同一个 WLAN 网络。
  2. 通过再次执行 adb connect 步骤重新连接。
  3. 如果上述操作未解决问题,重置 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 输出中(即使在您的桌面上可以看到该模拟器)。当存在以下所有情况时,便会出现这种问题:

  1. adb 服务器没有运行,以及
  2. 您在使用 emulator 命令时,将 -port-ports 选项的端口值设为 5554 到 5584 之间的奇数,以及
  3. 您选择的奇数号端口处于空闲状态,因此可以与指定端口号的端口建立连接,或者该端口处于忙碌状态,模拟器切换到了符合第 2 条中要求的另一个端口,以及
  4. 启动模拟器后才启动 adb 服务器。

避免出现这种情况的一种方法是让模拟器自行选择端口,并且每次运行的模拟器数量不要超过 16 个。另一种方法是始终先启动 adb 服务器,然后再使用 emulator 命令,如下例所示。

示例 1:在下面的命令序列中,adb devices 命令启动了 adb 服务器,但是设备列表未显示。

停止 adb 服务器,然后按照所示顺序输入以下命令。请提供系统中有效的 avd 名称。要获取 avd 名称列表,请输入 emulator -list-avdsemulator 命令位于 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 命令时必须指定目标设备。为此,请使用 devices 命令获取目标设备的序列号。获得序列号后,请结合使用 -s 选项与 adb 命令来指定序列号。如果您要发出很多 adb 命令,可以将 $ANDROID_SERIAL 环境变量设置为包含序列号。如果您同时使用 -s$ANDROID_SERIAL,则 -s 会替换 $ANDROID_SERIAL

在以下示例中,adb 先获得已连接设备的列表,然后使用其中一台设备的序列号在该设备上安装 helloWorld.apk

    $ adb devices
    List of devices attached
    emulator-5554 device
    emulator-5555 device

    $ adb -s emulator-5555 install helloWorld.apk
    

注意:如果您在多台设备可用时发出命令但未指定目标设备,则 adb 会生成错误。

如果有多个可用设备,但只有一个是模拟器,请使用 -e 选项将命令发送至该模拟器。同样,如果有多个设备,但只连接了一个硬件设备,请使用 -d 选项将命令发送至该硬件设备。

安装应用

您可以使用 adb 的 install 命令在模拟器或连接的设备上安装 APK:

    adb install path_to_apk
    

安装测试 APK 时,必须结合使用 -t 选项和 install 命令。要了解详情,请参阅 -t

要详细了解如何创建可安装在模拟器/设备实例上的 APK 文件,请参阅构建和运行应用

请注意,如果您使用的是 Android Studio,则无需直接使用 adb 在模拟器/设备上安装您的应用。Android Studio 会为您执行应用的打包和安装操作。

设置端口转发

您可以使用 forward 命令设置任意端口转发,将对特定主机端口上的请求转发到设备上的其他端口。以下示例介绍了如何设置主机端口 6100 到设备端口 7100 的转发:

    adb forward tcp:6100 tcp:7100
    

以下示例介绍了如何设置主机端口 6100 到 local:logd 的转发:

    adb forward tcp:6100 local:logd
    

将文件复制到设备/从设备复制文件

您可以使用 pullpush 命令将文件复制到某个设备或从中复制文件。与 install 命令(仅将 APK 文件复制到特定位置)不同,pullpush 命令使您能够将任意目录和文件复制到设备中的任何位置。

要从设备中复制某个文件或目录(及其子目录),请使用以下命令:

    adb pull remote local
    

要将某个文件或目录(及其子目录)复制到某个设备,请使用以下命令:

    adb push local remote
    

localremote 替换为开发计算机(本地)和设备(远程)上的目标文件/目录的路径。例如:

    adb push foo.txt /sdcard/foo.txt
    

停止 adb 服务器

在某些情况下,您可能需要终止 adb 服务器进程,然后重新启动以解决问题(例如,如果 adb 不响应命令)。

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

adb 命令参考

您可以从开发计算机上的命令行发出 adb 命令,也可以通过脚本发出。用法如下:

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

如果只有一个模拟器在运行或者只连接了一个设备,则默认将 adb 命令发送至该设备。如果有多个模拟器在运行并且/或者连接了多个设备,则您需要使用 -d-e-s 选项指定应向其发送命令的目标设备。

下表列出了所有支持的 adb 命令并解释了它们的含义和用法。

表 1. 可用的 adb 命令和选项

全局选项 说明
-a 在所有网络接口上监听,而非只在 localhost 上监听。
-d 将 adb 命令发送至唯一连接的 USB 设备。如果连接了多个 USB 设备,则返回错误。
-e 将 adb 命令发送至唯一运行的模拟器。如果有多个模拟器在运行,则返回错误。
-s serial_number 将 adb 命令发送至以其 adb 分配的序列号命名的特定设备(如“emulator-5556”)。替换存储在 $ANDROID_SERIAL 环境变量中的序列号值。请参阅将命令发送至特定设备
-H server adb 服务器主机的名称。默认值为 localhost
-P port adb 服务器端口号。默认值为 5037
-L socket 在提供的 adb 服务器套接字上监听。默认值为 tcp:localhost:5037
常规命令 说明
devices [-l] 输出所有设备的列表。-l 选项用于包含设备描述。要了解详情,请参阅查询设备
help 输出支持的 adb 命令及其描述的列表。
version 输出 adb 版本号。
run-as package_name 在设备上将命令作为应用运行(通过 package_name 指定)。因此,您在 adb 中运行命令就如同您指定的应用在运行相应命令一样(即您拥有该应用所具有的设备访问权限),无需请求 root 权限。在未取得 root 权限的设备或带有 Play 商店映像的模拟器上使用 adb 时,这可能很有必要。应用必须可调试。
网络命令 说明
connect host[:port] 通过 TCP/IP 连接到设备。如果您未指定端口,则使用默认端口 5555
disconnect [host | host:port] 断开与在指定端口上运行的指定 TCP/IP 设备的连接。如果未指定主机或端口,则所有设备都将与所有 TCP/IP 端口断开连接。如果指定了主机,但未指定端口,则使用默认端口 5555
forward --list 列出所有转发的套接字连接。
forward [--no-rebind] local remote 将套接字连接从指定的本地端口转发到设备上指定的远程端口。您可以通过以下方式指定本地和远程端口:
  • tcp:port。要选择任何开放端口,请将 local 值设置为 tcp:0
  • localabstract:unix_domain_socket_name
  • localreserved:unix_domain_socket_name
  • localfilesystem:unix_domain_socket_name
  • dev:character_device_name
  • jdwp:pid
forward --remove local 移除指定的转发套接字连接。
reverse --list 列出设备的所有反向套接字连接。
reverse [--no-rebind] remote local 反向连接套接字。--no-rebind 选项表示如果指定的套接字已通过之前的 reverse 命令完成绑定,则反向连接失败。您可以通过以下方式指定本地和远程参数的端口:
  • tcp:port。要选择任何开放端口,请将 remote 值设置为 tcp:0
  • localabstract:unix_domain_socket_name
  • localreserved:unix_domain_socket_name
  • localfilesystem:unix_domain_socket_name
reverse --remove remote 从设备中移除指定的反向套接字连接。
reverse --remove-all 从设备中移除所有反向套接字连接。
文件传输命令 说明
push local remote 将文件和目录从本地设备(计算机)复制到设备上的远程位置。
pull [-a] remote local 将远程文件和目录复制到设备中。-a 选项用于保留文件的时间戳和模式。
sync  [system|vendor|oem|data|all] 将本地编译版本从 $ANDROID_PRODUCT_OUT 中的指定位置同步到设备。所有变更文件均从指定的分区复制。默认设置是同步所有分区。此命令仅在您编译 Android 平台源代码时使用。应用开发者不需要使用此命令。

$ANDROID_PRODUCT_OUT 环境变量由 Android 编译系统自动设置,用于包含系统映像的位置。执行 adb sync 时通常不需要设置 $ANDROID_PRODUCT_OUT,但是如果您未使用编译树(但有编译树),或者在编译树之间进行同步(但不进行切换),这将很有帮助。


    $ANDROID_PRODUCT_OUT=/out/target/product/generic
    adb sync
    
应用安装命令 说明
install [options] package 将软件包推送到设备并进行安装。可能的选项如下:
  • --abi abi-identifier:针对特定 ABI 强制安装应用。
  • -l:具有转发锁定功能的应用。
  • -r:替换现有应用。
  • -t:允许安装测试软件包。如果使用开发者预览版 SDK(如果 targetSdkVersion 是字母,而非数字)编译 APK,则安装测试 APK 时必须在 install 命令中包含 -t 选项。要了解详情,请参阅 -t 选项
  • -s:在 SD 卡上安装应用。
  • -d:允许版本代码降级(仅用于调试软件包)。
  • -g:授予所有运行时权限。
install-multiple [options] packages

具有和 install 相同的选项,并且增加了以下选项:

-p:对应用进行部分安装。

uninstall [-k] package 从设备中移除此应用软件包。添加 -k 选项可保存数据和缓存目录。
备份和恢复命令 说明
backup [-f file] [-apk | -noapk] [-obb | -noobb] [-shared | -noshared] [-all] [-system | [-nosystem] package_names 将设备数据的归档写入 file。如果您未指定文件名,则默认文件为 backup.adb。当您指定 -all-shared 选项时,package 列表为可选项。下面介绍了其他选项的用法:
  • -apk | -noapk:备份或不备份 .apk 文件。默认值为 -noapk
  • -obb | -noobb:备份或不备份 .obb 文件。默认值为 -noobb
  • -shared | -noshared:备份或不备份共享的存储空间。默认值为 -noshared
  • -all:备份所有已安装的应用。
  • -system | -nosystem:备份所有已安装应用 (-all) 时包含或不包含系统应用。默认值为 -system
restore file file 中恢复设备内容。
调试命令 说明
bugreport path bugreport 输出到指定路径。如果 path 是目录,则错误报告使用默认文件名 bugreport.zip 保存到该目录下。如果设备不支持压缩格式的错误报告,则输出到 stdout
jdwp 输出给定设备上可用的 JDWP 进程的列表。您可以使用 forward jdwp:pid 连接到特定的 JDWP 进程。例如:
adb forward tcp:8000 jdwp:472
jdb -attach localhost:8000
logcat [-help] [option] [filter-spec] 将日志数据输出到屏幕。要了解 logcat 命令和 $ANDROID_LOG_TAGS 环境变量,请参阅 Logcat 页面上的过滤日志输出

$ADB_TRACE 环境变量包含要记录的调试信息列表(以英文逗号分隔)。具体值可以是 alladbsocketspacketsrwxusbsyncsysdepstransportjdwp 的任意组合。

另请参阅 Logcat 命令行工具

安全命令 说明
disable-verity userdebug 编译版本上停用 dm-verity 检查。dm-verity 选项可确保设备在用户启动后的状态与上次使用时的状态一样。要了解详情,请参阅验证启动
enable-verity userdebug 编译版本上重新启用 dm-verity 检查。dm-verity 选项可确保设备在用户启动后的状态与上次使用时的状态一样。要了解详情,请参阅验证启动
keygen file 生成 adb 公开和私有 RSA 加密密钥。私钥存储在 file 中。公钥存储在 file.pub 中。首次使用 adb 通过 USB 进行连接时,需要 RSA 密钥对。您必须接受主机的 RSA 密钥,才能明确授予 adb 对设备的访问权限。

您可以使用 $ANDROID_VENDOR_KEYS 环境变量指向某个文件或目录,其中包含使用 keygen 命令生成的 2048 位 RSA 身份验证密钥对。这些密钥对是对 adb 服务器生成的 RSA 密钥对的补充。

当 adb 服务器需要密钥时,它会先搜索 adb 服务器密钥存储库目录。如果找不到任何密钥,它会接着检查 $ANDROID_VENDOR_KEYS 环境变量以寻找位置。如果还是找不到任何密钥,本地 adb 服务器会生成一个新密钥对,并将其保存在 adb 服务器密钥存储库目录中。因此,只有生产全新 Android 设备的 OEM 需要自己运行 'adb keygen'

默认情况下,adb 服务器生成的密钥对以 adbkey(私钥)和 adbkey.pub(公钥)的形式存储在以下密钥存储库目录中:

  • Linux 和 Mac:$HOME/.android
  • Windows:%USERPOFILE%\.android
脚本命令 说明
wait-for [-transport] -state 等待设备处于指定状态。
  • state:值可以是 devicerecoverysideloadbootloader
  • transport:值可以是 usblocalany
get-state 输出设备的 adb 状态。adb 状态可以是 print offlinebootloaderdevice。要了解详情,请参阅查询设备
get-serialno 输出 adb 设备序列号字符串。要了解详情,请参阅查询设备
get-devpath 输出 adb 设备路径。
remount 在读写模式下重新装载 /system/vendor/oem 分区。
reboot [bootloader | recovery | sideload | sideload-auto-reboot ] 重新启动设备。此命令默认启动系统映像,但也支持 bootloaderrecovery
  • bootloader 选项重新启动到引导加载程序。
  • recovery 选项重新启动到恢复模式。
  • sideload 选项重新启动恢复模式并启动 sideload 模式。
  • sideload-auto-reboot 选项与 sideload 一样,但它在完成旁加载后会重新启动。
sideload otapackage 将指定的完整 OTA 软件包旁加载(以 APK 格式安装)到设备上。
root 使用 root 权限重新启动 adbd。
unroot 在不使用 root 权限的情况下重新启动 adbd。
usb 重新启动监听 USB 的 adb 服务器。
tcpip port-number 重新启动监听指定端口上的 TCP 的 adb 服务器。
内部调试命令 说明
start-server 检查 adb 服务器进程是否正在运行。
kill-server 终止 adb 服务器进程。
reconnect 从主机强制重新连接。
reconnect device 从设备强制重新连接。
Shell 命令 说明
shell 在目标设备中启动远程交互式 shell。要了解详情,请参阅发出 shell 命令
shell -e escape_char [-n] [-T] [-t] [-x] [command] 在目标设备中发出 shell 命令,然后退出远程 shell。您可以使用以下选项的任意组合:
  • -e:用于指定转义字符;如果您不想使用转义字符,则使用值 none。如果您未提供值,则使用默认的转义字符(破折号 (-))。
  • -n:不从 stdin 读取数据。
  • -T:停用伪终端实用程序 (PTY) 分配。
  • -t:强制进行 PTY 分配。
  • -x:停用远程退出代码和 stdout/stderr 分隔符。

要了解详情,请参阅发出 shell 命令

emu command 运行模拟器控制台命令。要了解详情,请参阅通过命令行控制模拟器

发出 shell 命令

您可以在进入或不进入设备上的 adb 远程 shell 的情况下,使用 shell 命令通过 adb 发出设备命令。要在不进入远程 shell 的情况下发出单个命令,请使用如下 shell 命令:

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

或者,使用如下命令进入设备上的远程 shell:

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

当您准备退出远程 shell 时,请按 Ctrl + D 或输入 exit

shell 命令二进制文件存储在设备的文件系统中,其路径为 /system/bin/

注意:在 Android 平台工具 23 及更高版本中,adb 与 ssh(1) 命令处理参数的方式相同。这项变更解决了很多命令注入方面的问题,还使安全执行包含 shell 元字符的命令(如 adb install Let\'sGo.apk)成为可能。不过,这项变更还意味着,对包含 shell 元字符的所有命令的解释也发生了变化。例如,adb shell setprop foo 'a b' 命令现在会返回错误,因为单引号 (') 会被本地 shell 消去,设备看到的是 adb shell setprop foo a b。要使该命令正常运行,请引用两次,一次用于本地 shell,另一次用于远程 shell,与处理 ssh(1) 的方法相同。例如,adb shell setprop foo "'a b'"

调用 Activity 管理器 (am)

在 adb shell 中,您可以使用 Activity 管理器 (am) 工具发出命令以执行各种系统操作,如启动某项 Activity、强行停止某个进程、广播 intent、修改设备屏幕属性,等等。在 shell 中,相应的语法为:

    am command
    

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

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

表 2. 可用的 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 实例启动监控。通常情况下,目标 componenttest_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]:提供进程名称时,指定要转储的进程的用户;如果未指定,则使用当前用户。
  • -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 将指定的 intent 规范以 URI 的形式输出。

请参阅 intent 参数的规范

to-intent-uri intent 将指定的 intent 规范以 intent: URI 的形式输出。

请参阅 intent 参数的规范

intent 参数的规范

对于采用 intent 参数的 Activity 管理器命令,您可以使用以下选项指定 intent:

调用软件包管理器 (pm)

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

    pm command
    

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

    adb shell pm uninstall com.example.MyApp
    

表 3. 可用的软件包管理器命令。

命令 说明
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 指定)安装到系统。

具体选项:

  • -l:安装具有转发锁定功能的软件包。
  • -r:重新安装现有应用,保留其数据。
  • -t:允许安装测试 APK。如果您只运行或调试了应用,或者使用了 Android Studio 的 Build > Build APK 命令,Gradle 便会生成一个测试 APK。如果使用开发者预览版 SDK(如果 targetSdkVersion 是字母,而非数字)编译 APK,则安装测试 APK 时必须在 install 命令中包含 -t 选项
  • -i installer_package_name:指定安装程序软件包名称。
  • -s:在共享的大容量存储设备(如 sdcard)上安装软件包。
  • -f:在内部系统内存上安装软件包。
  • -d:允许版本代码降级。
  • -g:授予应用清单中列出的所有权限。
uninstall [options] package 从系统中移除软件包。

具体选项:

  • -k:移除软件包后保留数据和缓存目录。
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 输出设备支持的最大用户数。

调用设备政策管理器 (dpm)

为便于您开发和测试设备管理(或其他企业)应用,您可以向设备政策管理器 (dpm) 工具发出命令。使用该工具可控制 Active Admin 应用,或更改设备上的政策状态数据。在 shell 中,相应的语法为:

    dpm command
    

您也可以直接从 adb 发出设备政策管理器命令,无需进入远程 shell:

    adb shell dpm command
    

表 4. 可用的设备政策管理器命令

命令 说明
set-active-admin [options] component 组件设置为 Active Admin。

具体选项包括:

  • --user user_id:指定目标用户。您也可以传递 --user current 以选择当前用户。
set-profile-owner [options] component 组件设置为 Active Admin,并将其软件包设置为现有用户的配置文件所有者。

具体选项包括:

  • --user user_id:指定目标用户。您也可以传递 --user current 以选择当前用户。
  • --name name:指定简单易懂的组织名称。
set-device-owner [options] component 组件设置为 Active Admin,并将其软件包设置为设备所有者。

具体选项包括:

  • --user user_id:指定目标用户。您也可以传递 --user current 以选择当前用户。
  • --name name:指定简单易懂的组织名称。
remove-active-admin [options] component 停用 Active Admin。应用必须在清单中声明 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 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 实用程序。该实用程序将屏幕 Activity 录制为 MPEG-4 文件。您可以使用此文件创建宣传视频或培训视频,或将其用于调试或测试。

在 shell 中,使用以下语法:

    screenrecord [options] filename
    

要从命令行使用 screenrecord,请输入以下命令:

    adb shell screenrecord /sdcard/demo.mp4
    

按 Ctrl + C(在 Mac 上为 Command+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 的设备上录制视频。
  • 某些设备可能无法以它们的本机显示分辨率进行录制。如果在录制屏幕时遇到问题,请尝试使用较低的屏幕分辨率。
  • 不支持在录制时旋转屏幕。如果在录制期间屏幕发生了旋转,则部分屏幕内容在录制时将被切断。

表 5. screenrecord 选项

选项 说明
--help 显示命令语法和选项
--size widthxheight 设置视频大小:1280x720。默认值是设备的本机显示分辨率(如果支持);如果不支持,则使用 1280x720。为获得最佳效果,请使用设备的 Advanced Video Coding (AVC) 编码器支持的大小。
--bit-rate rate 设置视频的视频比特率(以 MB/秒为单位)。默认值为 4Mbps。您可以增加比特率以提升视频品质,但这么做会导致视频文件变大。下面的示例将录制比特率设为 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) 会收集已安装应用的执行配置文件,这些配置文件用于优化应用性能。您可能需要检查收集的配置文件,以了解在应用启动期间,系统频繁执行了哪些方法和使用了哪些类。

要生成文本格式的配置文件信息,请使用以下命令:

    adb shell cmd package dump-profiles package
    

要检索生成的文件,请使用:

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

其他 shell 命令

如需所有可用 shell 程序的列表,请使用以下命令:

adb shell ls /system/bin

大多数命令都提供帮助说明。

下表列出了一些比较常用的 adb shell 命令。

表 6. 一些其他 adb shell 命令

Shell 命令 说明
dumpsys 将系统数据转储到屏幕。要详细了解此命令行工具,请阅读 dumpsys
dumpstate 将状态转储到文件。
logcat [option]...  [filter-spec]... 启用系统和应用日志记录,并将输出显示到屏幕上。

另请参阅 Logcat 命令行工具

dmesg 将内核调试消息输出到屏幕。
start 启动(重启)设备。
stop 停止执行设备。
sqlite3 启动 sqlite3 命令行程序。

sqlite3 工具包含用于输出表格内容的 .dump 以及用于输出现有表格的 SQL CREATE 语句的 .schema 等命令。您也可以随时执行 SQLite 命令。

SQLite3 数据库存储在文件夹 /data/data/package_name/databases/ 中。

例如:


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

要了解详情,请参阅 sqlite3 命令行文档