adbutils 实战指南：半小时上手 Python 控制安卓设备的自动化脚本

【免费下载链接】adbutilspure python adb library for google adb service.项目地址: https://gitcode.com/gh_mirrors/ad/adbutils

周五下班前，领导丢来一句话："明天这批测试机，每台都要装上新版 App，再把首页截图收集上来。" 数了数桌上的设备——八台真机加两台模拟器。要是用传统 adb 命令一台台敲，光是安装和截图就能耗掉一个下午。这时候你需要的，是一个能写在脚本里、循环跑完所有设备的 Python ADB 库：adbutils。它是 Google ADB 服务的纯 Python 实现，把 "连设备、装应用、传文件、截图录屏、模拟输入" 全部收进几十个直观 API 里，让繁琐的重复操作变成几行循环代码。

第一步：装好 adbutils 运行环境（两种途径任选）

先记住这一条就够用了：adbutils 本质是一个普通 Python 包，安装方式和其他库没有区别。

途径一：pip 一行命令装完

最省事的方式，直接交给包管理器：

pip3 install adbutils

如果你后续要用到完整功能（比如命令行生成二维码、通过 HTTP 解析远程 APK），就装上带全部可选依赖的版本：

pip3 install adbutils[all]

途径二：从源码安装，方便改代码

想研究源码或贡献代码的人，可以克隆到本地再以开发模式安装：

git clone https://gitcode.com/gh_mirrors/ad/adbutils cd adbutils pip3 install -e .

小提示：-e是 editable 模式，改完源码立刻生效，不用重复安装。本库要求 Python 3.8 及以上。

第二步：把手机连上来（本地与远程一视同仁）

安装只是热身，真正的流程从"拿到一个设备对象"开始。所谓设备对象，就是后续所有操作的主语——你叫它d，之后d.xxx()就代表"在这台手机上做 xxx"。

列出当前所有设备

from adbutils import adb for device in adb.device_list(): print(f"发现设备: {device.serial}") # 串号，相当于手机的身份证

# 只有一台设备时，连串号都不用传 d = adb.device() # 多台设备时，必须指定串号，否则会直接报错 d = adb.device(serial="33ff22xx")

连接远程/网络设备

无线调试、云测机、局域网设备，都走这一步：

adb.connect("192.168.1.100:5555") # 等价于 adb connect adb.wait_for("192.168.1.100:5555", state="device", timeout=10) # 最长等 10 秒，直到设备上线

易踩的坑：adb.connect()只负责发起连接，不代表设备已就绪。建议连接后立刻wait_for确认状态，脚本才不容易半路翻车。

第三步：开始干活——装应用、查应用、卸应用

设备到手，先解决领导最着急的"装 App"任务。adbutils 的安装接口既吃本地文件，也吃网络地址：

# 装本地 APK d.install("build/app-release.apk") # 装远程 APK（适合 CI 里直接从制品库拉包） d.install("http://example.com/app.apk")

配合卸载和查询，一个完整的"换版本"流程就出来了：

d.uninstall("com.example.app") # 卸载旧版 d.install("build/app-release.apk") # 装新版 d.list_packages() # 列出所有已安装包，确认装没装上

真实场景加分项：批量给多台设备装包，只需套一层循环——这正是把 adbutils 写进自动化脚本的意义所在。

第四步：传文件——一条 push 一句 pull

App 装完，接下来要把测试配置、数据文件分发到每台设备，再把设备上的日志和截图收回来。文件传输走d.sync对象：

# 本地 -> 设备 d.sync.push("config.json", "/sdcard/atx/config.json") # 设备 -> 本地 d.sync.pull("/sdcard/crash.log", "crash_33ff22xx.log")

# 需要边下边处理大文件？用迭代器逐块读取 for chunk in d.sync.iter_content("/sdcard/bigfile.bin"): write_chunk(chunk)

小提示：pull会把远端文件拉到当前目录；多设备时给文件名拼上串号（如上），避免互相覆盖。

第五步：拿结果——截图、录屏、模拟输入

领导要求的"首页截图"就是这里了。adbutils 的截图接口是高频操作，值得单独记住：

d.screenshot("home_33ff22xx.jpg") # 保存到本地，一步到位

需要录一段操作过程留档，用录屏接口，设置好时长自动停止：

d.screenrecord("demo.mp4", duration=10) # 录 10 秒自动停

说明：录屏底层会根据环境自动选择 scrcpy 或 adb 原生方案，你只需调用统一接口。

光截图还不够，自动化里经常要"替手指点屏幕"。两个最常用的模拟输入接口：

d.send_keys("Hello, adbutils!") # 向当前输入框发送文本 d.keyevent("HOME") # 按下系统键，HOME/BACK/MENU 都支持 d.open_browser("https://example.com") # 直接唤起默认浏览器打开网址

易踩的坑：send_keys只能发文本，中文或特殊符号在部分设备上会丢字符；需要复杂输入时建议配合 shell 层做兜底。

第六步：处理翻车——超时、异常与通用 shell 兜底

脚本写得再顺，也架不住设备抽风。adbutils 的异常体系很干净，顶层异常是AdbError，超时有独立的AdbTimeout，接住即可：

from adbutils import AdbError try: d.shell("sleep 1", timeout=0.5) # 故意设很短，模拟慢命令 except AdbError as e: print(f"操作失败: {e}")

另外，凡是库里没有封装的命令，都可以用d.shell(...)直接打进设备执行——它是万能兜底：

output = d.shell("getprop ro.product.model") # 查设备型号 print(output.strip())

需要拿到退出码和完整 stdout/stderr 时，用d.shell2(...)会更顺手。

附：不写代码也能用——命令行快照

如果只是临时看一眼，python -m adbutils自带全套命令行，无需编程：

调优三件套：环境变量控制全局行为

多设备、多环境跑自动化时，靠环境变量就能省掉一半传参：

• ADBUTILS_ADB_PATH：指定 adb 可执行文件路径，系统里装了几个 adb 也不怕认错
• ANDROID_SERIAL：设置默认设备串号，之后adb.device()直接命中这台
• ANDROID_ADB_SERVER_PORT：指定 ADB 服务端口，默认 5037，多服务并存时很有用

相关资料

想深入某个细节，可以顺着这些路径直接读源码与文档：

• 设备操作核心实现：adbutils/_device.py
• ADB 协议细节：docs/PROTOCOL.md
• 文件同步测试示例：e2etests/test_device_sync.py

回头再看开头那个场景：装包、传配置、截图、收日志，全流程用 adbutils 写成一个脚本循环跑完，十分钟收工。这份 adbutils 安装教程只是起点，把它接进你的自动化脚本里，下一批设备再也不会占用你的下班时间。

【免费下载链接】adbutilspure python adb library for google adb service.项目地址: https://gitcode.com/gh_mirrors/ad/adbutils