零基础3分钟上手 adbutils：用 Python 掌控 Android 设备的完整实战指南

零基础3分钟上手 adbutils用 Python 掌控 Android 设备的完整实战指南【免费下载链接】adbutilspure python adb library for google adb service.项目地址: https://gitcode.com/gh_mirrors/ad/adbutils每次要装个 App、截个图、拉个日志都得在终端里敲一长串adb install、adb shell screencap再配一堆-s参数手一抖就出错。adbutils 就是一个纯 Python 实现的 ADB 客户端它把这些操作全部封装成几行直观的代码装上之后你会发现控制 Android 设备原来可以像写普通 Python 程序一样简单。这篇 adbutils 安装与使用指南会带你从零跑通第一个示例再完成一个完整的设备自动化任务。⚙️ 三分钟上手安装 adbutils 并跑通第一个示例pip 安装 adbutils 的两种方式最省事的方式是直接用 pip 安装一行命令搞定pip3 install adbutils如果你还想用它的附加能力比如解析 APK 信息的--parse功能就装完整版pip3 install adbutils[all]两种方式怎么选给你一张对比表安装方式适用场景命令基础版日常设备连接、shell、文件传输、截图pip3 install adbutils完整版需要解析 APK、体验全部命令行功能pip3 install adbutils[all]源码安装想改源码或参与贡献git clone https://gitcode.com/gh_mirrors/ad/adbutils adbutils然后进入目录执行pip3 install -e .提示在 zsh 里adbutils[all]需要加引号写成pip3 install adbutils[all]否则会报 no matches found。第一条代码列出并连接你的 Android 设备安装完成后先用手机连接电脑并确认手机已开启「开发者选项 → USB 调试」。然后新建一个 Python 文件粘贴下面这段from adbutils import adb # 列出当前所有已连接的设备 for d in adb.device_list(): print(发现设备:, d.serial) # 指定序列号拿到设备对象serial 用你手机上看到的 d adb.device(serial33ff22xx) print(设备状态:, d.get_state())验收结果运行时如果屏幕上打印出了你的设备序列号和device状态说明你已经成功用 adbutils 连上了设备可以进入下一节了。如果什么都没打印多半是 USB 调试没开或者驱动没装好。如果你只连了一台设备连序列号都不用写直接adb.device()就行但注意多台设备同时连接时不写序列号会直接抛RuntimeError这个问题后面避坑指南会细说。 完整实战用 adbutils 一条龙完成装应用→截图→取文件光会列设备还不够下面以一个真实任务为例给一台测试机部署一个 App启动它截图留证再把设备上的文件拉回电脑。整个过程串起 adbutils 最核心的四个能力设备连接、应用管理、屏幕操作、文件传输。第一步连接设备USB 与远程两种姿势USB 连接你已经会了。如果你要操作的是远程设备比如放在机房的手机可以这样连from adbutils import adb # 连接同一网段下开了 adb 网络的设备 print(adb.connect(192.168.1.100:5555)) # 等它真正上线最多等 10 秒 adb.wait_for(192.168.1.100:5555, statedevice, timeout10) d adb.device(serial192.168.1.100:5555)如果远程设备提示连不上先用 USB 连一次并在设备上执行d.tcpip(5555)开启网络调试之后就能无线连接了。第二步安装并启动你的 APK安装是日常最高频的操作adbutils 同时支持本地文件和网络 URL 两种来源d adb.device(serial33ff22xx) # 安装本地 APK d.install(demo.apk) # 或者直接安装网络上的 APK它会自动帮你下载 d.install(https://example.com/demo.apk) # 启动应用并确认它真的到了前台 d.app_start(com.example.demo) info d.app_current() print(info.package, info.activity) # 期望看到你的包名和 Activity不写代码的话命令行也能干同样的事python -m adbutils -i demo.apk直接安装加个-L参数还能装完自动启动。第三步截图、传文件收尾验证应用跑起来之后截一张图看看界面是否正常# 截图并保存到本地返回的是 PIL 图片对象 d.screenshot().save(screen.jpg) # 顺便看看屏幕分辨率 print(d.window_size()) # 例如 (1080, 1920)然后从设备上拉一份文件回来比如 App 写入的日志# 先往设备写个测试文件再拉回本地 d.sync.push(local.txt, /sdcard/remote.txt) d.sync.pull(/sdcard/remote.txt, local.txt)到这里你已经完成了连接 → 安装 → 启动 → 截图 → 传文件的完整闭环。命令行版同样支持python -m adbutils --push local.txt:/sdcard/remote.txt推文件python -m adbutils --screenshot screen.jpg直接截图存盘。 进阶技巧3 个新手不知道的提效姿势1. 用 shell2 拿到退出码告别盲执行d.shell()只返回命令输出命令到底成没成功你无从判断。换成d.shell2()退出码、标准输出、错误输出全都有ret d.shell2(echo 1; echo 2 12, v2True) print(ret.returncode) # 0 表示执行成功 print(ret.stdout) # 1\n print(ret.stderr) # 2\n自动化脚本里判断命令是否成功靠这个最靠谱。2. 用 track_devices 实时监控设备插拔在测试机房或 CI 环境里你需要知道设备什么时候掉线。adbutils 提供设备跟踪能力for event in adb.track_devices(): print(event.present, event.serial, event.status) # 输出示例True 33ff22xx device # False 33ff22xx absent命令行版更直观python -m adbutils --track它会实时打印设备状态变化就像加了时间戳的adb devices。3. 用 pidcat 看彩色日志排查问题效率翻倍排查 App 崩溃时黑白日志看得眼睛疼。adbutils 内置了 pidcat按进程过滤日志并着色显示python3 -m adbutils.pidcat com.example.demo效果就是下图的彩色日志流按包名过滤、自动标色一眼定位关键信息⚠️ 避坑指南常见报错与正确写法对照新手最容易踩的坑基本都集中在这几类直接对照着排查现象原因正确做法adb.device()抛 RuntimeError同时连着多台设备却没指定序列号改为adb.device(serial33ff22xx)远程设备一直 offline设备没开网络调试或不在同一网段先 USB 连接执行d.tcpip(5555)再adb.connect()并wait_for安装报INSTALL_FAILED_ALREADY_EXISTS包已存在且没有覆盖安装使用d.install(app.apk, uninstallTrue)或传flags[-r, -t]shell 命令长时间卡死不返回没有设置超时d.shell(sleep 60, timeout3)超时会抛AdbTimeout提示找不到 adb 可执行文件系统 PATH 里没有 adb设置环境变量ADBUTILS_ADB_PATH/path/to/adbDocker 容器里连不上设备容器默认访问不到宿主机的 127.0.0.1设置ANDROID_ADB_SERVER_HOSThost.docker.internal再给你一段错误写法 vs 正确写法的代码对比避免掉进最常见的坑# 错误多设备环境下不指定序列号 d adb.device() # 正确明确指定要操作哪台设备 d adb.device(serial33ff22xx)另外如果你日常只操作固定的一台设备可以设置环境变量ANDROID_SERIAL33ff22xx之后adb.device()不传参数也能正确选中它能少写很多重复代码。总结与下一步现在你已经能用 adbutils 完成设备连接、应用安装与启动、截图、文件传输这四件核心事了还学会了拿退出码、监控设备、看彩色日志这些进阶用法以及最常见的几个坑的解法。相比手动敲 adb 命令这套库让你把设备操作变成可复用、可测试的 Python 代码自动化测试和批量设备管理都能直接受益。想继续深挖这几个入口值得收藏官方协议文档docs/PROTOCOL.md设备核心实现源码adbutils/_device.py命令行入口实现adbutils/main.py文件同步实现adbutils/sync.py测试用例参考e2etests/test_device_sync.py现在就装上 adbutils把第一条device_list()跑起来开始你的第一次 Android 设备自动化体验吧【免费下载链接】adbutilspure python adb library for google adb service.项目地址: https://gitcode.com/gh_mirrors/ad/adbutils创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考