简介一份关于 Android Debug Bridge安卓调试桥的简明教程面向 Android 开发测试人员、自动化脚本爱好者及刚接触 adb 命令的初学者系统整理 ADB 的安装配置、环境变量设置、设备连接检测与常用操作命令。PDF 单文件仅 58KB内容精炼便于快速查阅可作为随身参考手册。文档从 adb version 验证安装、adb devices 检测联通入手逐步讲解 Android Studio 内置 SDK、官方 platform-tools 下载及离线部署等安装方式并给出截图、点击、滑动、返回键、开关机等高频指令范例。无论是编写自动化脚本还是日常调试都能按图索骥减少摸索时间。目前已有 500 余人浏览学习适合需要快速掌握 ADB 基础操作、排查连接问题或将其集成到工作流中的读者是一份轻量实用的入门资料。1. ADB 不是什么黑魔法一次说清 Android Debug Bridge 能帮你解决什么我第一次被 ADB 救回来是一台反复重启的安卓工控设备。屏幕亮不了但用 ADB 通过无线调试还是能连上去抓 logcat最后定位到是某个系统服务死循环。ADB全称 Android Debug Bridge也就是安卓调试桥是 Google 官方提供的命令行调试工具让电脑通过 USB 或无线网络和安卓设备的守护进程通信。它可以装应用、传文件、录屏截图、抓崩溃日志、模拟点击甚至在没有源码的情况下解析界面层级。适合开发者、测试工程师、维修工程师也适合做电视盒子、车机和 RK3588 这类嵌入式安卓设备的人。接下来这篇文章我就按自己上手的顺序把环境配置、设备授权、高频命令、常见翻车和自动化技巧完整过一遍每一步都能照着做。2. 先建好调试环境ADB 安装、驱动与 PATH 配置少走三小时弯路很多人第一次卡住不是不会敲命令而是“命令不存在的提示”先来了。这里需要先明确一个概念ADB 不是一个独立 IDE 工具它只是 platform-tools 工具包里的可执行文件。你需要把它放到系统能找到的位置并让设备被 Windows 正确识别。2.1 别下载奇怪的 mini 版直接使用官方 platform-tools如果你装过 Android Studio那么 SDK 目录下已经带了platform-tools/adb不需要额外下载。如果你没有 Android Studio也不需要为 ADB 装整个 IDE直接下载官方提供的 “SDK Platform Tools” 压缩包即可。解压后你会看到一个adb.exe、一个AdbWinApi.dll、一个AdbWinUsbApi.dll这三个文件必须保持同目录缺一个 ADB 都会闪退或提示 DLL 缺失。下载完成后先确认能不能找到它。打开终端执行adb --version如果能打印出版本信息说明你的环境已经就绪。如果提示“不是内部或外部命令”或“command not found”那就是 PATH 没配好。我见过有人图省事直接把 adb.exe 复制到C:\Windows\System32这样确实能用但后续升级或卸载时容易留坑不推荐。正确的做法是把整个 platform-tools 目录固定下来放到C:\platform-tools或D:\adb这种无中文无空格路径下。2.2 Windows 的 PATH 配置管理员找不到 adb 的根源配置 PATH 的目的是让任何终端窗口都能在任意路径下执行adb。Windows 下有两种常见写法:: 临时生效只作用于当前 cmd 窗口 set PATHC:\platform-tools;%PATH% :: 永久生效写入当前用户环境变量新开窗口生效 setx PATH %PATH%;C:\platform-tools第一种set只对当前终端窗口有效适合临时验证。第二种setx会修改注册表里的用户环境变量但有一个隐患如果你的 PATH 原本很长超过 1024 字符的setx会截断后面的内容导致系统里其他软件失效。所以我更推荐用图形界面改右键“此电脑 → 属性 → 高级系统设置 → 环境变量”在“用户变量”或“系统变量”里找到 Path新增一行C:\platform-tools确认保存后再新开终端。这里有个高频问题普通窗口能执行 adb但“以管理员身份运行”的终端报“找不到 adb”。原因是管理员窗口读取的是系统级 PATH而你刚才只写了用户级 PATH。解决方法是把路径加到“系统变量”里而不是用户变量然后重启终端。2.3 驱动装不对就是白搭设备管理器是查黑匣子的地方USB 连接安卓设备后Windows 不一定能直接识别。你需要的是“ADB Interface”驱动不是电脑上常见的手机 MTP 传输驱动。检查方式是在设备管理器里看有没有带黄色感叹号的设备。如果看到 “Android Composite ADB Interface” 或厂商自己的 ADB 设备说明驱动没问题如果看到 “ADB Interface” 上有感叹号需要补装驱动。常见做法是先用手机厂商官方驱动找不到再用通用 ADB 驱动。但通用驱动不是万能个别国产设备厂商修改了 PID/VID可能还是要用原厂工具。安装驱动后在终端里可以用下面的命令确认系统是否枚举到了 ADB 硬件wmic path win32_pnpentity where name like %ADB% get Name如果能列出设备名说明驱动层已经通。如果这里是空的那大概率不是adb devices列表为空的问题而是驱动根本没装好。2.4 别忽略 server 的启动机制TCP 5037 是它的默认营房ADB 使用的是 client-server 架构。你每执行一条adb命令命令行程序会去检查主机上有没有已经在跑的 ADB server没有的话会自动启动一个监听 TCP 5037 的进程。第一次执行命令时看到* daemon not running; starting now at tcp:5037这不是报错是正常启动日志。验证环境是否就绪推荐用以下两步adb start-server adb devicesstart-server会明确告诉你 server 是否启动成功。如果提示端口被占用或者could not read ok from adb server通常是另一个路径下的 adb 进程占了端口这会在后面的避坑章节专门展开。环境配到这里你已经可以进入下一步连一台真实设备。3. 连接与授权USB 调试从打开到 authorized以及无线 ADB 的两种姿势环境能跑通之后真正的难关是设备本身的连接状态。很多人在adb devices里看到unauthorized或offline就懵了。这一章我会拆开讲怎么打开 USB 调试为什么需要授权以及无线连接连不上时先查什么。3.1 打开开发者选项手机、电视盒子和车机的入口不完全一样标准安卓手机路径是“设置 → 关于手机 → 连续点击版本号 7 次”然后回到设置页会出现“开发者选项”进去打开“USB 调试”。这个对绝大多数手机、平板都有效。但如果你面对的是电视盒子、创维电视、机顶盒或者车载中控情况可能更隐蔽。有些品牌会把开发者选项藏在工厂菜单里或者要求先在遥控器上输入特定组合键。这类设备的“强制 ADB”往往需要查具体固件说明核心仍然是把设置里的adb_enable打开。我的习惯是先从设置 → 关于里找版本号连点多次看有没有“进入开发者模式”的提示而不是盲目装驱动。3.2 adb devices 显示 unauthorized授权文件决定了设备信不信任你把 USB 线插上第一次执行adb devices大概率会看到类似这样的输出List of devices attached emulator-5554 device R58N1234567 unauthorized注意device表示正常unauthorized表示设备拒绝或尚未确认电脑的调试身份。此时安卓设备屏幕会弹出“是否允许 USB 调试”的对话框需要勾选“始终允许此计算机进行调试”并点击确定。如果设备屏幕没有弹窗常见原因是你之前在开发者选项里撤销过授权或者设备上的“仅充电”模式没切换为“文件传输/Android Auto”模式。授权机制的原理是这样的电脑上的 adb client 会生成一对 RSA 密钥设备第一次连接时收到公钥弹窗确认后把公钥写入/data/misc/adb/adb_keys。之后这台电脑再连接设备比对到相同公钥就直接信任不再弹窗。所以unauthorized不是连接问题是信任问题。如果你点击“允许”后仍然反复授权失败可以去设备设置的“开发者选项”里点击“撤销 USB 调试授权”然后重新插拔线再执行adb kill-server adb deviceskill-server会杀掉电脑上的 server 进程重新连接时会重新发起握手。这操作在授权问题上作用很大但前提是设备端本身要弹窗。如果设备屏幕已锁或黑屏先解锁再试。3.3 摆脱 USB 线无线调试的两种姿势与正确端口无线调试分新旧两种方式。如果你的设备是 Android 11 及以上系统自带“无线调试”可以先不插线。你需要在设置里打开“无线调试”然后点“使用配对码配对设备”此时设备会给出一个 IP 和端口以及六位配对码。电脑端执行adb pair 192.168.1.20:39471 # 提示 Enter pairing code: 输入六位配对码配对成功后再用adb connect连接设备上显示的调试端口。注意 connect 的端口通常和 pair 的端口不是同一个别直接复制。如果你用的是 Android 10 及以下没有原生配对入口就需要先 USB 连接一次然后执行adb tcpip 5555 adb connect 192.168.1.20:5555tcpip 5555是让设备的 adbd 守护进程开始监听 TCP 5555后面connect的端口要与之对应。无线连接失败时先确认电脑和设备在同一个局域网再检查防火墙是否放行了对应端口。还有一条很容易被忽略如果设备锁屏后进入休眠无线连接会掉线这是正常现象重新亮屏再 connect。3.4 设备 offline不是命令写错了是链路状态不对adb devices能看到设备但状态显示offline这个状态比unauthorized更隐蔽。它表示 adb server 和设备有过通信但现在通道已死。常见诱因有两个一是设备锁屏后 USB 通道进入低功耗二是 USB 控制器不稳定。处理优先级是先按电源键点亮屏幕再拔插线最后重启 adb server。如果设备是车机或电视盒子检查是否是 USB 口供电不足换到背板直连的 USB 2.0 口试试。4. 高频命令实战adb 截图保存电脑、logcat 抓取日志与基础文件操作连接状态正常后真正值钱的是命令熟练度。这一章选的命令全部来自实际高频场景截图回传、日志抓取、安装卸载、屏幕信息和 UI 层级。我做车载测试时这组命令每天要敲几十次。4.1 截图和录屏让图片直接进电脑少一步 pull获取屏幕截图最简单的方式有两种。第一种是直接在电脑上生成图片不经过设备存储adb exec-out screencap -p D:\screen.pngexec-out的作用是把二进制输出原样交给电脑终端-p指定输出 PNG 格式重定向到本地文件。这个命令在 Windows cmd、PowerShell 和 Linux 终端下都有效是我最常用的方式。缺点是如果设备分辨率很高图片可能很大但通常可以接受。第二种方式是先存在设备再 pulladb shell screencap -p /sdcard/screen.png adb pull /sdcard/screen.png D:\screen.png这种方式多了一次设备写入和一次传输但胜在设备端能保留副本。录屏方式类似adb shell screenrecord --bit-rate 8000000 /sdcard/demo.mp4 adb pull /sdcard/demo.mp4 D:\demo.mp4注意screenrecord默认只能录制 3 分钟超过需要加--time-limit。录制过程中设备屏幕不能关闭否则文件会异常。4.2 logcat 抓取日志先清空再复现否则你抓的是陈年旧账排查闪退问题时正确顺序是先清空日志再操作应用复现问题然后抓日志落盘。adb logcat -c adb logcat -d -v time D:\logcat.log-c清空缓存-d表示 dump 当前缓存后退出不会一直挂着占用终端-v time让每行日志带上日期时间。如果日志量太大可以按包名过滤。Android 7 以上支持按 PID 过滤先查目标进程号adb shell pidof com.example.app adb logcat -d --pid12345 -v time D:\app.log如果想抓系统某个标签的崩溃栈比如AndroidRuntime可以这样adb logcat -d -s AndroidRuntime:E D:\crash.log-s是静默模式只显示指定 tag 的日志E表示 Error 级别。这里有个参数细节-s后面的tag:优先级不需要加空格多个过滤条件用空格隔开。如果日志文件在终端里乱码多半是没有-v time导致格式问题或者设备时区异常。4.3 安装卸载与文件传输把电脑当 U 盘用还能绕过后台限制安装 APK 最常用的是-r保留数据覆盖安装适合升级测试adb install -r D:\app-release.apk adb uninstall com.example.app如果安装失败终端会返回INSTALL_FAILED_开头的错误码常见如INSTALL_FAILED_ALREADY_EXISTS表示未加-r或签名不一致INSTALL_FAILED_OLDER_SDK表示最小版本不满足。卸载时如果提示 “Failure [DELETE_FAILED_INTERNAL_ERROR]”通常不是权限问题而是这个应用是系统内置应用普通 adb 卸载不掉需要 root 或者禁用应用。文件传输命令比较固定adb push D:\document.pdf /sdcard/ adb pull /sdcard/document.pdf D:\document.pdfpull在拉取大文件时如果卡住先看设备端屏幕是否休眠。我建议在测试机上执行adb shell svc power stayon true这条命令让设备在充电状态下保持常亮省掉一堆莫名的传输中断问题。想恢复自动休眠执行adb shell svc power stayon false。4.4 屏幕信息与方向设置adb shell wm 的真正边界wm子命令是获取和修改窗口管理器参数的入口常用于拿到设备实际显示区域和像素密度adb shell wm size adb shell wm density输出类似Physical size: 1080x2340。但注意wm本身并没有直接的“设置屏幕方向”子命令。热词里常见的“adb shell wm设置应用屏幕方向”正确做法是通过settings命令修改系统旋转参数# 关闭自动旋转 adb shell settings put system accelerometer_rotation 0 # 0 竖屏1 横屏左横2 反向横屏 adb shell settings put system user_rotation 1这样设置是系统级的所有应用都会被强制方向。恢复自动旋转就执行adb shell settings put system accelerometer_rotation 1这个命令在车机测试里很常用因为要模拟不同屏幕方向下的 UI 布局。要注意部分设备的settings put对 user_rotation 不生效因为它们用的是自定义显示服务这时只能通过wm size做辅助判断不能强改。4.5 uiautomator dump 抓取 UI 层级没有源码也能拿到控件坐标如果你想做自动化测试但手头没有应用源码uiautomator dump是最快的路径adb shell uiautomator dump /sdcard/ui.xml adb pull /sdcard/ui.xml D:\ui.xml执行成功后设备端会输出UI hierarchy dumped to: /sdcard/ui.xml。这个 XML 里包含控件树的 resource-id、text、content-desc 和 bounds。例如我想定位一个搜索框的坐标打开 XML 搜resource-id然后拿到bounds[68,300][720,400]再用adb shell input tap 394 350精确点击。它的核心作用是把界面变成可以被脚本读取的数据。但它的局限也很明显如果页面正在播放动画或者应用用了 Flutter/SurfaceView 这类自绘渲染dump 出来的层级可能只有一个节点拿不到子控件。解决办法是先在开发者选项里把三个动画缩放都设为关闭或者用adb shell settings put global animator_duration_scale 0再重新 dump。5. ADB 翻车避坑unauthorized、版本不匹配、uiautomator dump 失效的排查这一章全是真实踩坑记录。每一条都是先描述现象、再说原因、最后给解决路径照着操作基本能止血。5.1 版本冲突adb server version doesnt match this client现象在终端执行任意 adb 命令立刻出现类似adb server version (31) doesnt match this client (41); killing...的提示然后命令无响应。原因电脑上存在多个 ADB 可执行文件比如 Android Studio 自带一份、你手动解压了一份、某些刷机工具又带了一份。当前 PATH 中第一顺位的 adb 启动了 server但实际调用的命令行程序来自另一个版本两者协议不一致server 被强制杀死后重启陷入循环。解决先用where adb查看所有 adb 位置。以 Windows 为例可能列出多个路径只保留一个 platform-tools 目录把其他 adb.exe 改名或删除。然后检查后台进程tasklist | findstr /i adb如果有多个 adb.exe 进程全部结束再执行adb kill-server adb start-server最后确认where adb只剩一个路径。这个问题最容易出现在“先装过手机厂商工具又装 Android Studio”的环境中。5.2 unauthorized 与授权窗口不弹出别只会拔线现象adb devices一直显示unauthorized但设备上没有弹出“允许 USB 调试”的对话框。原因大概率是之前在某次调试中点击了“拒绝”或者在开发者选项里撤销过本机授权。设备端的 adb_keys 已不存在但电脑端旧密钥还在重新连接后设备不知道是否该信任。解决先去设备开发者选项里点击“撤销 USB 调试授权”这一步会清掉设备端所有电脑的公钥。然后插拔 USB重新选择“文件传输”模式这时应该会重新弹窗。如果还是不弹连续执行adb kill-server adb devices这能让握手重新开始。如果依然不弹检查你的数据线是不是只有充电线没有数据线芯换线比折腾驱动更快。5.3 uiautomator dump 用不了卡在 could not get idle state现象执行adb shell uiautomator dump后终端报ERROR: could not get idle state或者生成的文件里只有node根节点没有任何控件信息。原因设备界面当前不稳定系统认为 UI 线程还在动画或渲染中无法抓到稳定层级。锁屏、视频播放、拼多多这类页面加载慢的应用也容易触发。解决先点亮屏幕并解锁停留在目标页面至少 2 秒。如果你在做自动化先关掉系统动画adb shell settings put global window_animation_scale 0 adb shell settings put global transition_animation_scale 0 adb shell settings put global animator_duration_scale 0然后重新 dump。如果拿到的 XML 仍然没有坐标那说明当前界面不是原生控件渲染比如 Flutter 或游戏画面uiautomator 只能拿到一个 SurfaceView 节点无法继续。这种情况下不要死磕 dump改用截图 图像识别来定位坐标。5.4 设备在线但命令超时USB 口、线材和休眠的三角关系现象adb devices能看到设备状态为device但执行adb install、adb pull时长时间卡住最后报TimeoutException或closed。原因并不是 adb 逻辑出错而是物理链路不稳定。常见于 USB 延长线、前置面板 USB 口、USB 3.0 转接头。另外设备锁屏后 USB 会进入睡眠状态。解决优先把线插在主机后置 USB 2.0 口不要用扩展坞。用命令保持设备常亮adb shell svc power stayon true如果设备已经进入卡死状态拔插线还不行就在设备开发者选项里调低“USB 配置”相关权限或者切换一次“USB 调试”开关。我见过一条质量很差的短线能让 100MB 的 apk 传十分钟换线后问题当场消失。5.5 管理员身份找不到 adbPATH 被用户环境变量骗了现象普通 cmd 里adb version正常但“以管理员身份运行”的窗口中提示“不是内部或外部命令”。原因Windows 管理员窗口和普通窗口读取的环境变量集合可能不同。如果你用setx把 path 写进了用户变量管理员进程启动时可能不加载当前用户的 PATH导致找不到。解决不要用setx直接编辑环境变量把C:\platform-tools添加到“系统变量 Path”。添加后重新打开管理员窗口执行adb version如果还找不到就用完整路径验证环境是否配错C:\platform-tools\adb.exe version能运行说明只是 PATH 问题不能运行说明 platform-tools 目录本身缺文件重新解压一份再试。6. 把 ADB 变成你的自动化工具截图-日志-UI 一条命令搞定最后分享一个我一直在用的组合技巧把前面几章的命令封装成一条命令用于“复现 Bug 时的现场留痕”。做测试时最怕的是研发问“当时日志呢”有这套方法三秒内能把现场截图、系统日志、UI 层级一起存到电脑。我一般会在 Windows 上准备一个 Python 脚本比如adb_capture.pyimport subprocess, sys, os LABEL sys.argv[1] if len(sys.argv) 1 else debug OUT_DIR rD:\adb_capture os.makedirs(OUT_DIR, exist_okTrue) def sh(cmd): subprocess.run(cmd, shellTrue, checkTrue) # 1. 截图直接落盘到电脑 sh(fadb exec-out screencap -p {OUT_DIR}\\{LABEL}.png) # 2. 抓取当前日志开 -d 表示 dump 后退出 sh(fadb logcat -d -v time {OUT_DIR}\\{LABEL}.logcat) # 3. 抓取 UI 层级先存设备再 pull 到电脑 sh(fadb shell uiautomator dump /sdcard/{LABEL}.xml) sh(fadb pull /sdcard/{LABEL}.xml {OUT_DIR}\\{LABEL}.xml) print(fcaptured: {OUT_DIR})这个脚本有几个值得注意的地方截图用exec-out避免设备端垃圾文件日志用-d避免终端被刷屏UI dump 成功后才 pull失败会影响后续代码所以用shellTrue的checkTrue配合让它及时发现错误。使用时先确认 adb 已配置进 PATH然后接上设备执行python adb_capture.py bug_20250601你会在D:\adb_capture下得到三个文件文件名都带标签。如果设备没连接脚本会在第一条截图命令处报错并停止不会继续生成没意义的空文件。这个技巧的进阶方向是集成到自动化框架里把截图和日志写入常驻采集队列监听adb devices状态变化一旦设备离线就压缩现场数据。我现在的习惯是凡是排查不稳定问题先跑一次这个脚本留底再去复现。设备可能在你手里五分钟就走了但截图和日志永远还能翻得出来。希望帮到你。本文还有配套的精品资源点击获取