ADB 工具函数 Python 使用教程

环境准备

  1. 安装 Platform-Tools(官网下载) 并将其路径加入系统环境变量 PATH。
  2. 手机开启「开发者选项」中的「USB 调试」功能。

执行命令验证设备连接:

bash 复制代码
adb devices

输出中显示设备状态为 device 表示已授权成功。记录设备序列号,例如:3B158E00A3V00000。

核心函数:adb()

函数签名含义
python 复制代码
def adb(cmd: str, check: bool = True) -> str
  • cmd: 要执行的 ADB 命令字符串,如 'shell ls /sdcard'、'pull a.jpg D:/a.jpg'。
  • check: 是否检查返回码。若为 True 且命令失败,抛出异常;若为 False,返回空字符串,脚本继续运行。
推荐实现
python 复制代码
import subprocess
from pathlib import Path

DEVICE_SERIAL = "3B158E00A3V00000"  # 替换为你的设备序列号

def adb(cmd: str, check: bool = True) -> str:
    """执行 adb 命令。支持 shell、pull、push 等操作"""
    full_cmd = f"adb -s {DEVICE_SERIAL} {cmd}"
    result = subprocess.run(
        full_cmd,
        shell=True,
        capture_output=True,
        text=True,
        encoding="utf-8",
        errors="replace",
    )
    if check and result.returncode != 0:
        raise RuntimeError(f"ADB 失败: {full_cmd}\n{result.stderr}")
    return result.stdout.strip()
调用方式
python 复制代码
# 检查错误(默认行为),失败则抛异常
brand = adb("shell getprop ro.product.brand")

# 允许失败,不中断脚本,返回空串
raw = adb("shell ls /sdcard/Pictures", check=False)

# 截图并拉取
adb("shell screencap -p /sdcard/screen.png")
adb(r'pull /sdcard/screen.png D:\screen.png')

常用工具函数

推送图片(固定文件名,避免相册乱序)
python 复制代码
def push_image_to_phone(local_path: Path) -> str:
    # 步骤1:确保目录存在(不删除目录,保留 MediaStore 已有路径记录)
    adb(f"shell mkdir -p {PHONE_TMP_DIR}")

    # 步骤2:以固定文件名覆盖推送
    phone_path = f"{PHONE_TMP_DIR}/{PHONE_FIXED_FILENAME}"
    print(f"  [ADB PUSH] {local_path.name} → {phone_path}")
    adb(f'push "{local_path}" {phone_path}')

    # 步骤3:通知 MediaStore 重新扫描该路径,更新缩略图和索引
    adb(
        f"shell am broadcast -a android.intent.action.MEDIA_SCANNER_SCAN_FILE "
        f"-d file://{phone_path}",
        check=False
    )
    return phone_path

拉取单个文件或目录
python 复制代码
def pull_single_file(phone_path: str, local_dir: Path, rename: str = "") -> Path:
    local_dir.mkdir(parents=True, exist_ok=True)
    fname = rename or Path(phone_path).name
    local_dst = local_dir / fname
    adb(f'pull "{phone_path}" "{local_dst}"')
    return local_dst

获取手机目录下所有文件名(集合形式)
python 复制代码
def get_phone_dir_files(directory: str) -> set[str]:
    raw = adb(f"shell ls {directory}", check=False)
    if not raw:
        return set()
    return {line.strip() for line in raw.splitlines() if line.strip()}

差量拉取新生成的图片
python 复制代码
PHONE_DOWNLOAD_DIR = "/sdcard/Pictures"

def pull_new_images(before: set[str], output_dir: Path, prefix: str) -> list[Path]:
    after = get_phone_dir_files(PHONE_DOWNLOAD_DIR)
    new_files = after - before
    saved = []
    for fname in sorted(new_files):
        dst = output_dir / f"{prefix}_{fname}"
        adb(f'pull "{PHONE_DOWNLOAD_DIR}/{fname}" "{dst}"')
        saved.append(dst)
    return saved
用法示例
python 复制代码
before = get_phone_dir_files(PHONE_DOWNLOAD_DIR)
# ... 触发 App 生成内容 ...
saved = pull_new_images(before, Path(r"D:\output"), prefix="case001")
print(f"已保存 {len(saved)} 张新图片")

Shell / 按键速用

python 复制代码
adb("shell getprop ro.product.model")      # 获取设备型号
adb("shell input keyevent 4")              # 按返回键
adb("shell input keyevent 3")              # 按 Home 键
adb("shell input tap 540 960")             # 点击屏幕坐标 (540, 960)
adb("shell am force-stop com.larus.nova")   # 强制停止指定应用

最小可运行示例

python 复制代码
# demo_adb.py
from pathlib import Path

DEVICE_SERIAL = "3B158E00A3V00000"  # 替换为你的设备序列号

# 粘贴以下函数定义:
def adb(cmd: str, check: bool = True) -> str:
    full_cmd = f"adb -s {DEVICE_SERIAL} {cmd}"
    result = subprocess.run(
        full_cmd,
        shell=True,
        capture_output=True,
        text=True,
        encoding="utf-8",
        errors="replace",
    )
    if check and result.returncode != 0:
        raise RuntimeError(f"ADB 失败: {full_cmd}\n{result.stderr}")
    return result.stdout.strip()

PHONE_TMP_DIR = "/sdcard/doubao_tmp"
PHONE_FIXED_FILENAME = "doubao_upload.jpg"

def push_image_to_phone(local_path: Path) -> str:
    adb(f"shell mkdir -p {PHONE_TMP_DIR}")
    phone_path = f"{PHONE_TMP_DIR}/{PHONE_FIXED_FILENAME}"
    adb(f'push "{local_path}" {phone_path}')
    adb(
        f"shell am broadcast -a android.intent.action.MEDIA_SCANNER_SCAN_FILE "
        f"-d file://{phone_path}",
        check=False,
    )
    return phone_path

def get_phone_dir_files(directory: str) -> set[str]:
    raw = adb(f"shell ls {directory}", check=False)
    if not raw:
        return set()
    return {line.strip() for line in raw.splitlines() if line.strip()}

if __name__ == "__main__":
    print("brand =", adb("shell getprop ro.product.brand"))
    print("model =", adb("shell getprop ro.product.model"))
    files = get_phone_dir_files("/sdcard/Pictures")
    print("Pictures count =", len(files))

运行前确保设备已连接且授权。


常见问题

问题 解决方案
adb: command not found 检查 Platform-Tools 是否正确安装并加入 PATH
error: device not found USB 连接不稳定,尝试重新插拔或重启 ADB (adb kill-server, adb start-server)
图片未出现在相册 使用 am broadcast -a android.intent.action.MEDIA_SCANNER_SCAN_FILE 手动触发扫描
中文输入无效 改用 uiautomator2 的 set_text(),避免直接调用 input text
文件拉取失败(权限/路径) 确保路径存在,使用 mkdir -p 创建目录,避免路径拼写错误

设计要点(写脚本时记住)

  • 所有 ADB 调用必须通过封装函数 adb() 统一入口,禁止直接拼写 adb -s xxx。
  • 可能失败的操作(如 ls 空目录、广播扫描)使用 check=False 防止脚本中断。
  • 推送图片使用固定路径覆盖,避免因文件名随机导致媒体库污染。
  • 拉取结果采用差量集合比对,防止误拉历史文件,保证数据准确性。
  • 路径处理统一使用 Path,避免字符串拼接错误。
相关推荐
starzy199015 小时前
深入理解Scala隐式类:扩展方法机制
开发语言·人工智能·scala
M--Y16 小时前
LangGraph 工作流模式
开发语言·javascript·python·langchain·大模型·llm·langgraph
岁月宁静16 小时前
DeepSeek Harness 实战与架构解析:让 Agent 从“会聊”到“能交付”
人工智能·python·agent
LiaoWL12316 小时前
NumPy 入门实战(二):向量化与余弦相似度——从 ndarray 到 Embedding
python·numpy·embedding
forest_0917 小时前
多 Agent 协作第二课:交叉验证≠独立验证
人工智能·python·算法·机器学习·prompt·agi
吴可可12317 小时前
WScript Shell操作注册表详解
开发语言
纪念 22918 小时前
C++ 算法基础 (差分)
开发语言·c++·算法
databook20 小时前
时间序列数据,先拆规律还是先查异常
python·数据挖掘·数据分析
师夷长技以自愈20 小时前
手搓 AI Agent 第 8 篇:从手写循环到画流程图——LangGraph 封装
人工智能·python
aifannihao21 小时前
Rust 1.100 的 DropGuard:用 Python 实测失败回滚与吞异常
python·rust·异常处理·标准库·contextlib