Python-uiautomator2 环境配置与设备连接指南

最新推荐文章于 2026-02-27 14:28:51 发布

原创最新推荐文章于 2026-02-27 14:28:51 发布 · 887 阅读

本内容遵循CC 4.0 BY-SA版权协议

1. 环境配置：从“装好”到“能用”的关键一步

很多朋友在按照教程用 pip install uiautomator2 装好库之后，就兴冲冲地跑去写脚本了，结果一运行，十有八九会卡在设备连接这一步。屏幕上蹦出个连接超时或者设备未找到的错误，瞬间就懵了。我刚开始用的时候也这样，以为安装就是终点，其实那只是拿到了入场券，真正的“入场仪式”——环境配置，才刚刚开始。这一步没做对，后面所有的自动化操作都无从谈起。

简单来说，uiautomator2 的安装只是在你的电脑 Python 环境里放好了“指挥中心”。但你想遥控的手机，还是个“素人”，它听不懂指挥中心发来的指令。所以，我们需要在手机上安装一套“翻译官”和“执行器”系统。这个过程，就是 init 初始化。它可不是可有可无的选项，而是让电脑和手机建立通信桥梁的必由之路。这个指南，就是带你一步步走过这座桥，把“装好了”变成“真好用”。

我会假设你已经完成了最基础的 pip 安装，电脑上也有了可用的 adb 环境。咱们直接从安装后的第一步“初始化”开始，把设备连接、服务检查、常见坑点一个个捋清楚。目标是让你跑通第一个连接脚本，看到设备信息成功打印出来，那感觉，就像第一次打通了任督二脉。

2. 核心操作：设备初始化与深度连接

2.1 初始化：给手机装上“智能中枢”

安装完库之后，第一道命令也是最重要的一道命令来了：python -m uiautomator2 init。你可别小看这行命令，它背后干了不少体力活。我把它理解为“一键部署手机端自动化套件”。当你执行它时，你的电脑会通过 adb 主动找到已连接的手机，然后默默地给它安装好几个核心组件：

app-uiautomator.apk 和 app-uiautomator-test.apk：这是 Google Uiautomator2 测试框架的服务端应用。简单理解，它们是能在手机上运行、接收指令并操作屏幕的“机器人”。
atx-agent：这是一个常驻在手机后台的守护进程。它的作用至关重要，是电脑和手机上 Uiautomator2 服务之间的“通信总机”和“保活专员”，确保服务在需要时随时待命。
minicap 和 minitouch：这是两个高性能的底层工具。Minicap 用于高速截图，比传统 adb 截图快得多，在做图像识别或需要频繁检查屏幕时非常有用。Minitouch 则提供更精准、快速的触控模拟。它们都是提升自动化效率和稳定性的利器。

怎么执行呢？ 打开你的命令行终端（CMD、PowerShell 或 Terminal），直接输入上面那行命令回车就行。这时候，请务必确保你的手机已经用 USB 线连上电脑，并且开启了“开发者选项”中的“USB调试”。手机会弹出授权提示，一定要点击“允许”。然后你就能在终端里看到滚动的日志，显示一个个组件在下载和安装。

这里有个新手超级大坑：如果你电脑上通过 adb 连接了不止一台手机（比如模拟器开着，真机也连着），这条命令会默认给所有设备都进行初始化。这可能导致混乱，或者给不需要的设备也装上了应用。所以，更稳妥的做法是指定设备序列号（Serial Number）。

# 首先，查看当前连接的所有设备序列号
adb devices

# 你会看到类似这样的输出
# List of devices attached
# emulator-5554   device
# 9ABCDEF123456789        device

# 然后，针对特定序列号进行初始化，例如初始化那台真机
python -m uiautomator2 init --serial 9ABCDEF123456789

使用 --serial 参数进行初始化，是走向专业和稳定操作的第一步。它能避免很多因设备混淆导致的问题。

2.2 连接方式详解：USB与WIFI的抉择

初始化成功后，你的手机已经具备了被自动化控制的能力。接下来就是从 Python 脚本里连接它。uiautomator2 提供了两种主要的连接方式：USB 和 WIFI。它们各有适用场景，选对了能让脚本运行更顺畅。

USB 连接 (u2.connect()) 这是最直接、最稳定，也是我最推荐新手使用的方式。脚本里写一行 d = u2.connect() 就行，库会自动找到通过 USB 连接的第一台设备并建立连接。它的原理是利用 adb 的端口转发功能，在电脑和手机之间建立一条稳定的通信隧道。

优点：连接极其稳定，速度有保障，不受网络环境影响。脚本一执行，连接几乎瞬间建立。缺点：必须插着线，对于需要移动手机或远程操作的场景不太方便。 适用场景：本地开发、调试、稳定性要求高的自动化任务。

WIFI 连接 (u2.connect_wifi(“手机IP:端口”)) 这种方式让手机摆脱了线缆的束缚。你需要先知道手机在 WIFI 网络中的 IP 地址（一般在手机设置-关于手机-状态信息里查看），以及 atx-agent 服务的端口（默认是 7912）。

import uiautomator2 as u2

# 假设手机IP是 192.168.1.100
d = u2.connect_wifi("192.168.1.100:7912")

优点：无线连接，灵活自由，手机可以随意移动。缺点：稳定性依赖于 WIFI 网络质量，容易受干扰。首次连接前，通常需要先用 USB 执行一次 init 并启动 atx-agent。 适用场景：需要手机脱离电脑移动的测试（如测试不同房间的信号）、多设备同时操控、或者单纯不想插线。

我的经验：在开发调试阶段，永远优先使用 USB 连接。它能排除网络这个不稳定因素，让你快速定位问题是出在脚本逻辑还是环境上。等到脚本稳定了，再考虑切换到 WIFI 连接进行批量或远程执行。另外，很多人在公司网络下用 WIFI 连接失败，是因为公司网络设置了客户端隔离（AP隔离），导致电脑 ping 不通手机。这时候要么换家用网络，要么就得用 USB。

2.3 连接验证与信息获取

连接对象 d 创建之后，怎么知道真的连上了呢？最直观的方法就是打印设备信息。d.info 属性是一个包含了设备详细信息的字典。

import uiautomator2 as u2

d = u2.connect() # 或者 connect_wifi
print(d.info)

运行这段代码，如果一切正常，你会看到类似下面这样的输出：

{
    "currentPackageName": "com.android.settings",
    "displayHeight": 2400,
    "displayWidth": 1080,
    "displayRotation": 0,
    "productName": "PDKM00",
    "screenOn": true,
    "sdkInt": 30,
    "naturalOrientation": true
}

看到这个，恭喜你！这不仅仅是“连接成功”的信号，更是一个宝藏。displayHeight 和 displayWidth 是你编写点击坐标时的重要依据；currentPackageName 告诉你当前前台是哪个应用；sdkInt 是 Android 版本号，有时候某些操作需要根据系统版本做兼容性判断。我习惯在脚本开头先打印一下 d.info，既能验连接，又能顺手拿到屏幕分辨率，一举两得。

3. 避坑指南：常见问题与实战排查

理论说再多，不如踩一次坑。下面这些是我和同事们真金白银踩出来的常见问题，附上排查思路和解决方法，希望能帮你节省大量折腾的时间。

3.1 初始化失败：adb与权限的迷阵

问题现象：执行 python -m uiautomator2 init 时，卡住不动，或者报错 adb devices 列表为空、设备未授权。

排查步骤：

检查USB连接与调试：这是最最最常见的原因。换一根质量好的数据线试试（很多连接问题是劣质线导致的）。确保手机屏幕上弹出的“允许USB调试吗？”对话框点了“确定”。有的手机（如小米）还需要在开发者选项里打开“USB调试（安全设置）”。
重启adb服务：adb 服务有时会卡住。在命令行里执行两行命令：
```
adb kill-server
adb start-server
```
然后再次执行 adb devices，看看设备是否出现并显示为 device 状态（如果是 unauthorized 则是未授权，需要在手机上点确认）。
检查多设备情况：如果 adb devices 列出多个，一定要用 --serial 参数指定。模拟器和真机同时存在时，序列号很容易混淆。
网络问题：初始化时需要从 GitHub 下载组件。如果网络环境不好，可能会下载超时失败。可以尝试使用国内镜像源，或者在命令中指定离线文件（但这对于新手较复杂）。一个简单的重试方法：多执行几次初始化命令。

3.2 连接超时：服务未启动的幽灵

问题现象：脚本执行 u2.connect() 或 connect_wifi() 时，长时间等待后抛出超时（Timeout）错误。

排查步骤：

确认初始化成功：首先回忆或检查初始化是否真的成功了。可以去手机“设置”-“应用管理”里，看看有没有一个叫 ATX 或者 com.github.uiautomator 的应用。有的话，说明基础组件装上了。
手动启动服务：有时候 atx-agent 进程可能意外退出了。我们可以通过 adb 手动启动它：
```
adb shell am start -n com.github.uiautomator/.MainActivity
```
执行后，手机可能会短暂闪现一个黑色界面然后消失，这是正常的，表示服务被唤醒了。然后再运行你的连接脚本试试。
检查端口监听：对于 WIFI 连接，这是必查项。在电脑上，用 telnet 命令检查手机端口是否可通（Windows 用户可能需要先启用“Telnet客户端”功能）。
```
telnet 192.168.1.100 7912
```
如果黑屏或者连接失败，说明手机端的服务没在监听。需要回到上一步确保服务已启动，并检查手机防火墙是否屏蔽了该端口（一般不会）。
USB连接转WIFI连接的陷阱：如果你想用 WIFI 连接，但手机是第一次连接这台电脑，必须先用 USB 线成功连接并初始化一次，让电脑和手机完成配对。之后，可以在 USB 连接的状态下，执行一个命令将连接模式切换到 WIFI：
```
d = u2.connect() # 先用USB连上
d.set_new_command_timeout(300) # 可选，设置新命令超时时间
# 此时，设备会同时监听USB和WIFI端口
```
然后你就可以尝试使用 connect_wifi 了。直接拿一台全新的、从未USB连接过的手机就想用WIFI连，是行不通的。

3.3 运行中断：atx-agent的静默崩溃

问题现象：脚本运行一段时间后，突然失去响应，后续所有操作都失败。重新连接也报错。

原因与解决：这通常是手机端的 atx-agent 守护进程因为内存不足、系统清理后台等原因被“杀”掉了。uiautomator2 在设计上已经考虑了这一点，提供了自动重连机制，但前提是 atx-agent 本身有自我恢复的能力。

检查 atx-agent 版本：老版本的 atx-agent 稳定性较差。确保你初始化时安装的是最新版本。你可以通过重新执行 python -m uiautomator2 init 来更新手机端组件。

脚本中加入健壮性判断：在长时间运行的脚本中，不要假设连接永远有效。可以在关键操作步骤前后，加入简单的健康检查，比如尝试获取 d.info，如果失败则尝试重新连接。

import uiautomator2 as u2
import time

def safe_click(d, selector):
    try:
        d(selector).click()
    except Exception as e:
        print(f"操作失败，尝试重新连接: {e}")
        d = u2.connect() # 重新连接
        time.sleep(2)
        d(selector).click() # 重试操作

# 在循环中使用
for i in range(100):
    safe_click(d, text="下一步")

锁屏与省电模式：确保手机设置为“永不休眠”，并且将自动化测试应用（如ATX）加入省电模式的白名单，防止系统休眠时中断服务。

4. 进阶配置：让环境更加强健

当你能稳定连接设备后，可以再看看这些进阶配置，它们能提升你的自动化体验和脚本的可靠性。

4.1 指定设备序列号连接

在有多台设备需要管理的场景下，在代码中硬编码连接方式是不现实的。更优雅的做法是动态获取或指定序列号。

import uiautomator2 as u2
import os

# 方法1：通过环境变量传递设备号（适合CI/CD环境）
device_serial = os.getenv("ANDROID_DEVICE_SERIAL", "") # 如果没设置环境变量，则为空
if device_serial:
    d = u2.connect(device_serial) # connect() 函数可以直接传入序列号
else:
    d = u2.connect() # 默认连接第一个

# 方法2：连接所有设备，进行批量操作
import uiautomator2 as u2
all_devices = u2.list() # 列出所有通过adb连接设备的序列号
device_objects = []
for serial in all_devices:
    dev = u2.connect(serial)
    device_objects.append(dev)
    print(f"已连接设备: {serial}, 信息: {dev.info['productName']}")

# 现在可以对 device_objects 列表里的所有设备执行相同操作
for dev in device_objects:
    dev.screen_on() # 例如，点亮所有设备的屏幕

4.2 调整超时与延迟参数

默认的连接和操作超时时间可能不适合所有网络或手机状况。特别是对于性能较差的低端机或网络波动大的 WIFI 环境，适当调大超时参数能避免很多偶发性失败。

import uiautomator2 as u2

# 在连接时就可以设置全局超时
d = u2.connect(timeout=15.0) # 将连接超时从默认的10秒改为15秒

# 也可以后续单独设置新命令的超时（针对每个操作的等待时间）
d.set_new_command_timeout(60) # 单位是秒，设置单个操作命令的超时时间为60秒

# 对于点击、输入等操作，有时需要增加一点隐式等待时间，等待元素出现
d.implicitly_wait(10.0) # 设置隐式等待10秒

implicitly_wait 这个参数特别有用。它意味着当你的脚本执行如 d(text="确定").click() 时，如果屏幕上没有立刻出现“确定”这个文本控件，库会自动等待你设定的时间（这里是10秒），在此期间不断查找，一旦找到就立即点击。这比自己在代码里写 time.sleep 要智能和高效得多。

4.3 使用设备快照与输入法管理

两个非常实用的高级功能：

设备快照 (Snapshot)：在脚本失败时，自动截屏保存现场，是调试的神器。

import uiautomator2 as u2
import datetime

d = u2.connect()
try:
    d(text="不存在的按钮").click()
except Exception as e:
    # 出错了，立刻截图保存，文件名带上时间戳
    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
    screenshot_path = f"error_screenshot_{timestamp}.png"
    d.screenshot(screenshot_path)
    print(f"操作失败，已保存截图至: {screenshot_path}")
    raise e

输入法管理：自动化中输入文本是个高频操作，但手机上的第三方输入法可能会带来干扰（如联想词、表情面板）。

d = u2.connect()
# 切换到 uiautomator2 自带的简易输入法，它不会弹出任何多余界面
d.set_fastinput_ime(True)
d.clear_text() # 清空输入框
d.send_keys("Hello uiautomator2") # 直接输入，非常稳定

# 操作完成后，可以切换回原来的输入法
d.set_fastinput_ime(False)

这些技巧都是在实际项目中一点点积累起来的。环境配置和连接看似是准备工作，但它奠定了整个自动化项目稳定性的基石。花点时间把这些步骤理顺、摸熟，后面写业务逻辑脚本时才会事半功倍，不至于被各种莫名其妙的环境问题折腾得焦头烂额。好了，现在你的 uiautomator2 环境应该已经就绪，设备也连上了，可以尽情地去探索 Android 自动化的世界了。

标签