云手机脚本使用教程:安装配置、执行失败与循环控制方法

先想清楚:脚本在云手机上到底是怎么跑的

云手机本质上是运行在机房服务器里的安卓实例,你通过客户端远程看到画面、点击屏幕,而脚本就装在实例内部运行,和你在一台真机上跑没什么两样,区别只在于它不需要你的实体手机一直亮着屏幕。理解这一点很关键:脚本能不能长期稳定,很大程度上取决于实例本身是否稳定在线,而不只是脚本写得多聪明。

所以这篇教程的顺序是:先把实例环境准备好,再把脚本装进去、配好参数,然后学会看报错、改循环。三步走完,一个能跑一整天的脚本基本就成型了。

安装前的三件事:环境、权限、网络

很多人一上手就直接传脚本、点运行,结果第一步就失败。安装之前先把下面三件事确认好,能省掉后面 80% 的无效排查。

第一,实例的安卓版本与架构。大部分自动化框架依赖无障碍服务或 ADB 调试接口,安卓版本过低会缺少对应 API,架构不匹配会导致安装包直接装不上。创建实例时先看清系统版本,脚本工具链按这个版本去选。

第二,权限要一次性给足。安卓 11 以后,无障碍服务、悬浮窗、后台运行、电池优化白名单这几项缺一个,脚本就可能跑着跑着被系统回收。安装完第一件事就是进设置逐一打开,别等到报错了再回头找。

第三,网络要能通路。脚本如果需要访问外部接口,先在实例内打开浏览器试一下能否正常加载;如果通过 ADB 连接,确认端口映射与控制台给出的连接信息一致。

脚本安装与基础配置:一步一步来

安装本身不复杂,难点在于把连接参数和启动参数写对。以常见的 ADB 连接方式为例,控制台会给出实例的连接地址和端口,先跑通连接,再谈脚本。

# 第一步:确认能连上云手机实例
adb connect 127.0.0.1:5555
adb devices

# 第二步:安装自动化运行环境或脚本 APK
adb install -r automation-env.apk

# 第三步:把配置文件和脚本推送到实例内部
adb push config.json /sdcard/script/config.json
adb push main.py /sdcard/script/main.py

连接成功后,把脚本里的设备地址、等待时长、目标应用包名做成可配置项,不要硬编码在代码里。以后换实例、换应用,只改配置文件,不用动代码,这是脚本能不能长期维护的分水岭。

import json
import time
import uiautomator2 as u2

with open('/sdcard/script/config.json', 'r', encoding='utf-8') as f:
    cfg = json.load(f)

# 连接实例,地址来自配置文件
d = u2.connect(cfg['device'])

# 启动目标应用并等待界面稳定
d.app_start(cfg['package'])
time.sleep(cfg['startup_wait'])

# 判断关键控件是否出现
if d(text=cfg['ready_text']).exists(timeout=10):
    print('界面就绪')
else:
    print('界面未就绪,需要排查')

这里有个小技巧:先只用 print 打日志,不要急着做点击。把每一步的判断结果打出来,确认脚本「看得见」界面,再去加动作,调试效率会高很多。

执行失败?按这个顺序排查

脚本报错时最忌讳东改一点西改一点。建议按「连接 → 权限 → 界面 → 逻辑」的顺序自上而下排查,绝大多数问题在第二层就能定位。

现象常见原因处理方向
连接直接被拒绝地址或端口填错,实例未启动回到控制台核对连接信息,确认实例处于运行状态
脚本启动几秒就退出无障碍服务未开启,被系统回收开启无障碍与后台白名单,关闭电池优化限制
找不到控件,超时报错界面还没加载完,或文案已改版加长等待时间,改用 id 或层级定位代替文字定位
偶发成功、偶发失败网络波动或元素渲染延迟引入重试机制和指数退避等待
跑一段时间卡死内存泄漏,日志文件占满空间定时清理缓存与日志,定期重启应用

还有一个特别容易被忽略的点:日志一定要落到文件里。只靠客户端看一眼画面,你永远不知道失败发生在第几步。把每一步的时间戳和结果写进日志,排查时间能从几小时缩短到几分钟。

循环控制的三种写法与适用场景

循环控制是脚本翻车最集中的地方。常见的问题有三类:死循环跑飞、异常直接把整个脚本带崩、任务做完不会自己停。下面三种写法基本能覆盖九成场景。

写法一:固定次数循环。适合「刷固定轮数」的任务,跑完就退出,最安全也最好控。

for i in range(cfg['rounds']):
    print('第 %s 轮开始' % (i + 1))
    do_task()
    time.sleep(cfg['interval'])
print('全部轮次完成,脚本退出')

写法二:带重试上限的 while 循环。适合界面加载不稳定、需要「一直试到成功为止」但又要防止无限重试的场景。

max_retry = cfg['max_retry']
retry = 0
success = False

while retry < max_retry and not success:
    try:
        if d(text=cfg['ready_text']).exists(timeout=5):
            do_task()
            success = True
        else:
            retry += 1
            time.sleep(min(2 ** retry, 30))   # 指数退避,最长等 30 秒
    except Exception as e:
        retry += 1
        print('第 %s 次异常: %s' % (retry, e))
        time.sleep(5)

if not success:
    print('达到重试上限,任务跳过')

写法三:主循环 + 心跳检查。适合需要长时间挂机的场景。主循环里每轮都检查一次实例是否还正常、任务队列是否为空,异常就重启应用而不是重启整个脚本。

while True:
    if not is_instance_alive():
        restart_app()
        time.sleep(10)
        continue

    if not has_pending_task():
        print('任务队列已空,安全退出')
        break

    run_one_task()
    time.sleep(cfg['interval'])

三种写法的核心差别在于「退出条件」和「异常兜底」。写循环时先问自己两个问题:什么时候停?出错以后谁负责收尾?想清楚这两点,脚本就不会跑飞。

让它稳定跑一整天的几个小习惯

脚本能跑起来只是起点,能跑一整天才是目标。几个成本很低但收益很高的习惯:

一是把等待时间做成可调参数,不同网络状况下随手改,不用重新打包。二是定时清理日志和缓存,实例存储满了,脚本会以各种奇怪的方式失败。三是循环里加一个心跳检查,实例掉线时能自己恢复,而不是傻等。四是关键步骤做截图留证,出问题时有图可看。

另外,如果你的脚本需要 7×24 小时常驻,选一个在线稳定的云端安卓实例比不断优化脚本更有效。畅畅云手机(ccloudphone)提供云端安卓实例,实例在机房侧持续运行,你可以在客户端随时查看运行画面,配合脚本内的重试与心跳机制,长期挂机的成功率会明显提升。把脚本装进实例、参数配好,剩下的交给它在云端跑就行。

畅畅云手机云端实例长期在线运行示意

常见问题

Q:脚本安装成功了,但一打开就闪退怎么办?
先看架构和安卓版本是否匹配,再检查无障碍、悬浮窗、后台运行这几项权限是否都开了。多数闪退都是权限缺失导致的。

Q:为什么脚本在本地手机正常,放到云手机就报找不到控件?
常见原因是分辨率与等待时间不同。云实例的渲染速度和本地不一致,把超时时间调长,并改用 id 或层级定位代替文字定位,通常就能解决。

Q:循环里怎么防止死循环把实例拖垮?
给循环设一个明确的次数上限或超时时间,并在异常分支里累加计数,达到上限就退出并记录日志。永远不要写没有出口的 while True。

Q:脚本跑几个小时后变慢甚至卡死,是什么原因?
通常是内存累积和日志占满存储。每隔固定轮次重启一次目标应用、定期清理日志目录,能大幅缓解。

Q:循环里的重试间隔设多少合适?
不要固定 1 秒狂试。建议用指数退避,从 2 秒开始逐次翻倍,设一个上限(比如 30 秒),既不会触发接口限制,也不会浪费太长时间。