Android 调试桥 (adb) 基础知识点

Android 调试桥 (adb) 是一种功能多样的命令行工具，可让您与安卓手机进行通信。常用于辅助测试开发或定位问题。

一、adb的工作原理 🌟

1. 启动服务器进程：检查是否adb服务器进程正在运行，若没有则启动。
   • 启动或关闭adb服务：adb start-server、adb kill-server
2. 绑定端口：服务器进程与本地TCP端口5037绑定。（所有 adb 客户端均使用端口 5037 与 adb 服务器通信）
3. 监听adb客户端发出的命令
4. 扫描查找模拟器：服务器扫描5555～5585之间的奇数号端口查找模拟器（供前 16 个模拟器使用）。
5. 建立连接：服务器一旦发现 adb 守护程序 (adbd)，便会与相应的端口建立连接。
   PS：每个模拟器都使用一对按顺序排列的端口：一个用于控制台连接的偶数号端口，另一个用于 adb 连接的奇数号端口。（adb连接=奇数号，控制台连接=奇数号-1）
   • 自动连接：在设备的系统设置中启用 USB 调试，用数据线连接到电脑，手机弹窗确认授权。
   • 手动连接：adb connect 设备序列号
6. 可使用 adb 命令访问设备

adb基础命令

• start-server: 确保ADB服务器正在运行。
• kill-server：终止正在运行的ADB服务器。
• -a: 指定adb server监听同一局域网下所有网络接口，而不仅仅是localhost。
• -d: 指定使用USB连接的设备。（多个会报错）
• -e: 指定使用TCP/IP连接的设备（多个会报错）。
• -s SERIAL: 通过设备的序列号指定要操作的设备。
• -H: 指定adb server的主机名（默认是localhost）。
• -P: 指定adb server的端口（默认是5037）。
• -L SOCKET: 指定adb server监听的socket（默认是tcp:localhost:5037）。
• help: 显示帮助信息。
• version: 显示adb的版本号。

二、设备连接与识别

1、连接设备

• 物理连接（USB） 🌟：
  电脑启动adb服务 + 手机开启USB调试 + 使用数据线插入电脑USB插口 + 电脑上安装USB驱动程序 + 手机确认授权

• 网络连接 🌟（同一个局域网Wi-Fi下的TCP/IP连接）：
  物理连接成功 + adb tcpip <port>设备上的守护进程（adbd）监听指定端口 + 断开USB连接 + adb connect <device_ip_address>:<port>连接设备

• 网络连接 - 反向连接 (Reverse Connection)：本质还是建立在物理连接或者网络连接的基础之上，设备连接成功后，解决无法直接访问开发机特定端口的问题，通过端口转发，在设备上调试运行在开发机上的服务。
  请求过程：USB连接 >> adb reverse tcp:<device_port> tcp:<local_port> 建立反向连接 >> 开发机上启动服务监听端口请求 >> 手机应用上发起API请求localhost:<设备端口>时，将对应端口的请求转发到开发机对应端口上 >> 开发机上的后端服务处理请求 >> 响应沿着原路（ADB 服务端 -> USB -> 设备 adbd -> 应用）返回给 Android 应用。

• 通过 Android 调试桥接工具 (如 scrcpy, Vysor)，本质还是建立在物理连接或者网络连接的基础之上。

• 通过 Android Studio 的虚拟设备管理 (AVD Manager)：Android Studio 在启动模拟器时，会自动配置并连接到 adb。

• 特殊模式连接：

  • Recovery 模式: USB连接，adb devices 可能能看到设备（序列号可能不同），状态通常是 recovery 或 sideload 而不是 device。用于刷写第三方 Recovery、卡刷包、救砖等。
  • Bootloader / Fastboot 模式: USB连接，adb devices 看不到设备，需要使用 fastboot devices 命令来查看设备，用于刷写分区、解锁 Bootloader 等底层操作。

通过TCP/IP连接设备：

• connect HOST[:PORT]: 通过TCP/IP连接到设备，默认端口5555。
• disconnect [HOST[:PORT]]：断开指定TCP/IP设备的连接，如果不指定则断开所有。
• reconnect：从主机端强制重新连接设备。这个命令会断开当前连接并尝试重新连接设备。
• reconnect device：从设备端强制重新连接。这个命令会通知设备断开与当前主机的连接，然后重新连接。
• reconnect offline：将离线（offline）或未授权（unauthorized）的设备重置，强制其重新连接。
• pair HOST[:PORT]: 与设备进行配对，用于安全的TCP/IP通信（Android 11及以上）。

2、查看已连接设备

查看已连接设备：adb devices 支持-l查看设备信息，格式为：<设备序列号> <连接状态> <设备信息>，输出如下：

List of devices attached
127.0.0.1:5555         device product:cancro_x86_64 model:Mate_10_Pro device:x86_64 transport_id:1

• 物理设备：设备的硬件序列号（Serial Number, SN）
• 模拟器： 格式为 emulator-<端口号>（例如 emulator-5554）。
• 网络设备： 通过 adb connect <ip:port> 连接的设备会显示其 IP 地址和端口号（如 192.168.1.100:5555）。

已连接多个设备时，通过-s <serial>指定设备：adb -s 127.0.0.1:5555 ...

3、设备状态识别

• device（已授权并可用）：
  正常可访问的状态。

• offline（设备未响应/未完成授权）：
  adbd 进程崩溃/未启动、USB 线/端口问题、设备处于不稳定状态（如刚启动）、ADB 版本与设备不兼容。

• unauthorized（用户未在设备上授权 USB 调试）：
  设备已连接，但用户尚未在设备弹出的 “Allow USB debugging?” 对话框中点击 “Allow”。

• no permissions（Linux/Mac 下常见权限问题）：
  ADB 没有足够的权限访问 USB 设备。

• no devices/empty list：
  没有检测到任何连接的设备或模拟器。

4、设备连接异常排查

确认连接方式相关联的连接要素，有针对性的排查。

5、端口转发

端口转发：

• forward --list: 列出所有正向端口转发。
• forward [--no-rebind] LOCAL REMOTE: 建立端口转发。
  • 如果使用--no-rebind，当本地端口已经被转发时，命令会失败。
  • 支持的转发类型比如tcp:<端口号>：TCP端口
• forward --remove LOCAL: 移除指定的转发。
• forward --remove-all: 移除所有转发。

反向端口转发（reverse）：

• reverse --list: 列出所有反向端口转发（从设备到主机）。
• reverse [--no-rebind] REMOTE LOCAL: 建立反向端口转发。
• reverse --remove REMOTE: 移除指定的反向转发。
• reverse --remove-all: 移除所有反向转发。

三、应用包管理

1、安装与卸载

adb install 命令

在主机（PC）上执行的命令，用于将PC上的APK文件安装到设备。

• 安装1个APK包：install [-lrtsdg] [--instant] PACKAGE
• 安装1个/多个APK包(空格隔开)：install-multi-package [-lrtsdpg] [--instant] PACKAGE...
• 为单个包安装多个APK：install-multiple [-lrtsdpg] [--instant] PACKAGE...（拆解APKs的场景）
• 卸载：uninstall [-k] PACKAGE

参数说明：

• -r（replace）: 覆盖安装
• -t（test）: 允许安装测试包（针对 AndroidManifest 中的 android:testOnly）
• -d（downgrade）: 允许降级安装 (仅可调试的包可用)
• -p（partial）: 部分安装 (仅安装APKs可用)
• -g（grant）: 自动授予所有运行时权限（Android 6.0+）
• --instant：应用无需完整安装即可运行，但功能受限（不能使用后台服务、开机启动等）
• --no-streaming：禁用流式安装。将整个 APK 文件推送到设备后再触发安装
• --fastdeploy：启用快速部署，比较设备上现有 APK 和新 APK 的差异，仅推送差异部分
• --no-fastdeploy：禁用快速部署
• -k（keep）：卸载但保留数据和缓存目录（仅卸载可用）

adb shell pm install命令

在设备shell中执行的命令，用于安装设备上已经存在的APK文件。

• pm install [-lrtsfd] [-i PACKAGE] [--user USER_ID] [PATH]
  
• 卸载：pm uninstall [-k] [--user USER_ID] PACKAGE

adb install 与pm install的区别

1. 执行位置不同

2. 文件路径处理

3. 权限要求对比

4. 功能覆盖范围

pm install在自动化方向的优势：

• 文件传输和安装完全解耦，传输/安装故障隔离，可分段处理，比如弱网超时可重试
• 错误信息处理：pm install返回系统级错误信息（含Java堆栈）
• CPU占用和内存波动较稳定

2、应用查询

列出应用包名：adb shell pm list packages [-s3fi]

• -s：系统应用
• -3：第三方应用
• -f：显示 APK 路径
• -i：显示安装来源

3、应用数据管理

• adb shell pm clear PACKAGE：清楚应用数据。
• adb shell pm path PACKAGE：获取 APK 包路径。
• adb shell dumpsys package PACKAGE：导出包数据。
• adb backup -f data.ab PACKAGE：数据备份。
• adb restore data.ab：恢复应用数据。

4、应用状态控制

组件级控制：

# 禁用特定 Activity
adb shell pm disable com.example.app/.MainActivity

5、权限管理

权限查询：

# 查看应用权限状态
adb shell dumpsys package com.example.app | grep -A 20 "Permissions:"

四、文件操作

1、文件上传

从本地电脑端将文件传至远程设备上：push [--sync] [-zZ] LOCAL... REMOTE

• --sync：增量同步，仅传输更新文件
• -z：启用压缩，传输时压缩数据
• -Z：禁用压缩，原始数据传输

2、文件下载

从远程设备上获取文件到本地电脑端：pull [-azZ] REMOTE... LOCAL

• -a：保留元数据，包括时间戳和权限

五、日志与调试信息获取

1、bugreport - 系统诊断报告

adb bugreport [PATH]

2、logcat - 日志分析工具

adb logcat [options] [filterspecs]

📝 基本输出控制

• -s
  设置默认静默过滤（等效于 *:S），推荐写法："*:S"、\*:S
• -v <format>
  设置日志输出格式，可选值：
  brief, color, long, printable, process, raw, tag, thread, threadtime, time, usec
• -D
  在日志缓冲区之间打印分隔线

💾 文件输出与轮转

• -f <filename>
  将日志输出到文件（默认 stdout）
• -r <kbytes>
  按指定 KB 大小轮转日志文件（需配合 -f）
• -n <count>
  设置保留的轮转日志文件数量（默认 4，需配合 -f）

🔍 日志读取模式

• -d
  转储日志后立即退出（非阻塞模式）
• -c
  清空整个日志缓冲区并退出
• -L
  输出上次重启前的日志

⏳ 筛选特定日志范围

• -t <count>
  仅显示最近 <count> 行日志（隐含 -d）
• -t '<time>'
  显示指定时间后的日志（格式 MM-DD hh:mm:ss.mmm，隐含 -d）
• -T <count>
  持续显示最近 <count> 行日志（不隐含 -d）
• -T '<time>'
  持续显示指定时间后的日志（不隐含 -d）

🎯 过滤规则（filterspecs）

优先级等级

• V：Verbose（最详细，单个标签默认优先级）
• D：Debug（通配符 * 默认优先级）
• I：Info
• W：Warn
• E：Error
• F：Fatal
• S：Silent（完全屏蔽）

规则语法

• <tag>[:priority]
  示例：
  • ActivityManager:I → 显示该标签 Info 及以上日志
  • *:W → 显示所有标签 Warning 及以上日志
• 多规则组合：
  adb logcat Tag1:I Tag2:D *:S
  （显示 Tag1 的 Info+ 和 Tag2 的 Debug+，屏蔽其他所有标签）
• 静默过滤：
  *:S 强制屏蔽所有日志（常配合其他规则使用）

六、其他

📋 ADB 环境变量

1. ADB_TRACE

作用：控制 ADB 调试信息的输出级别
格式：逗号分隔的列表（可多选）
可选值：

• all：所有调试信息
• adb：ADB 基础命令
• sockets：套接字通信
• packets：数据包传输细节
• rwx：文件读写操作
• usb：USB 连接详情
• sync：文件同步过程
• sysdeps：系统依赖操作
• transport：传输层活动
• jdwp：Java 调试协议

示例：

# 启用 USB 和传输层调试
export ADB_TRACE=usb,transport
adb devices  # 将显示详细调试日志

2. ADB_VENDOR_KEYS

作用：指定自定义 ADB 密钥文件/目录（用于设备认证）
格式：冒号分隔的路径列表
典型场景：

• 使用非默认 adbkey（如企业内部分发密钥）
• 多密钥管理（同时支持个人和公司设备）

示例：

# 添加两个密钥位置
export ADB_VENDOR_KEYS=~/.android/company_key:/custom_keys
adb connect 192.168.1.10  # 使用指定密钥认证

3. ANDROID_SERIAL

作用：设置默认连接的设备序列号（等效于 adb -s <序列号>）
使用场景：

• 多设备连接时自动选择目标设备
• CI/CD 流水线中指定特定测试设备

示例：

# 设置默认设备序列号
export ANDROID_SERIAL=emulator-5554
adb shell  # 自动连接到 emulator-5554

4. ANDROID_LOG_TAGS

作用：预设 logcat 过滤规则（等效于 logcat <filterspecs>）
格式：与 logcat 过滤规则相同（<tag>:<priority>）
注意：优先级字母需大写（V/D/I/W/E/F/S）

示例：

# 只显示 Error 及以上日志
export ANDROID_LOG_TAGS="*:E"
adb logcat  # 自动应用过滤

# 多规则组合
export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"

5. ADB_LOCAL_TRANSPORT_MAX_PORT

作用：设置本地传输扫描的最大端口号（用于检测模拟器）
默认值：5585
计算规则：

• 端口范围 = 5555 到 5555 + 16*(N-1)
• 其中 N = ADB_LOCAL_TRANSPORT_MAX_PORT
  最大支持模拟器数：16（默认）

示例：

# 支持扫描 32 个模拟器
export ADB_LOCAL_TRANSPORT_MAX_PORT=32
adb devices  # 可检测更多模拟器

🛠️ 使用技巧

1. 临时设置（当前终端有效）：

   export ANDROID_SERIAL=emulator-5556
   adb shell
   

2. 永久配置（添加到 shell 配置文件）：

   # 添加到 ~/.bashrc 或 ~/.zshrc
   echo 'export ANDROID_LOG_TAGS="*:W"' >> ~/.zshrc
   source ~/.zshrc
   

3. 组合使用：

   # 调试 USB 连接并指定设备
   export ADB_TRACE=usb
   export ANDROID_SERIAL=84B7N163020000123
   adb shell
   

⚠️ 注意事项

• 优先级：命令行参数 > 环境变量 > 默认值
  （如 adb -s emulator-5554 会覆盖 $ANDROID_SERIAL）
• 端口限制：修改 ADB_LOCAL_TRANSPORT_MAX_PORT 需重启 ADB 服务生效

  adb kill-server && adb start-server
  

• 密钥安全：ADB_VENDOR_KEYS 中的私钥需设置 600 权限

  chmod 600 ~/.android/custom_key
  

七、进阶

adb shell命令 = 标准 Linux Shell 命令 + Android 专用工具和命令