1. 代码开发工具不止IDE:用Python把ADB/Fastboot命令封装成可复用函数
“代码开发工具”这个词很容易被理解成IDE、编译器或调试器,但我实际做设备侧自动化时,一个用Python写的命令行封装脚本同样属于代码开发工具。它把adb和fastboot的重复调用、状态判断、超时重试收进几个函数里,避免手动敲一长串命令时漏掉中间状态。下面这个脚本面向Android设备管理场景,能检测设备处于ADB还是Fastboot,自动切换并执行解锁、分区写入、清数据和重启。适合需要批量处理设备或远程协助的开发者,也适合刚接触subprocess、想找一个能跑起来的封装例子照着改的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具的环境底座:subprocess调用、30秒超时与3次重试
2.1 命令执行为什么选subprocess.run
脚本第一层要解决的问题是“怎么安全地执行外部命令”。很多入门写法会直接拼字符串交给os.system,命令输出只能打到终端,退出码也拿不到,后续想判断设备状态就只能靠人眼。这里用subprocess.run,把命令拆成列表传进去,不经过shell解释,既避免了路径里有空格时的拼接问题,也方便捕获stdout和stderr。返回的returncode、stdout、stderr三个值,正好支撑后面的状态检测和错误日志。
配置区只放两个全局参数:TIMEOUT = 30和MAX_RETRIES = 3。前者给每条外部命令一个上限,后者只在分区刷写里用。把这两个数抽到文件顶部,后面调参时不用钻进函数体里翻。
python复制import subprocess
import sys
import time
import os
# 配置区:定义常用命令超时时间与重试次数
TIMEOUT = 30
MAX_RETRIES = 3
def run_command(cmd, timeout=TIMEOUT):
"""
执行系统命令并返回输出。
:param cmd: 命令列表
:param timeout: 超时时间
:return: (returncode, stdout, stderr)
"""
try:
result = subprocess.run(
cmd,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
timeout=timeout,
text=True,
encoding='utf-8',
errors='ignore'
)
return result.returncode, result.stdout.strip(), result.stderr.strip()
except subprocess.TimeoutExpired:
return -1, "", "Command timed out"
except FileNotFoundError:
return -2, "", "Command not found. Please install platform-tools."
这段函数里有几个参数值得展开。text=True让stdout和stderr以字符串返回,省去手动decode;encoding='utf-8'配合errors='ignore',是为了应对部分设备输出里混入非UTF-8字符时脚本直接崩掉。timeout参数设成30秒是经验值:adb devices和fastboot devices通常秒回,fastboot flash在镜像不大时也够用;但遇到驱动异常或USB口供电不稳,命令可能挂住,不设上限就会把整个脚本卡死。捕获TimeoutExpired后返回-1,捕获FileNotFoundError后返回-2,调用方不用再关心异常类型,只看返回码就能分流。
2.2 run_command的返回值约定:0、-1、-2分别代表什么
写自动化脚本最怕“失败了但不知道失败在哪”。这个脚本用三个返回码把常见情况分开:0表示命令执行完且退出码为0;-1表示超时;-2表示系统找不到adb或fastboot可执行文件。调用方拿到-2时,基本可以判定是环境没配好,而不是设备问题。
| 返回码 | 含义 | 典型触发场景 | 调用方处理 |
|---|---|---|---|
| 0 | 命令正常结束 | adb devices、fastboot devices、fastboot flash 成功 | 继续解析输出 |
| -1 | 命令超时 | USB线接触不良、驱动卡住、fastboot等待设备响应 | 提示检查连接,必要时调大TIMEOUT |
| -2 | 命令不存在 | platform-tools未安装或未加入PATH | 提示安装工具或把脚本与platform-tools放同目录 |
| 其他非0 | 命令自身报错 | 镜像路径错、分区名错、设备状态不对 | 打印stderr,按具体错误处理 |
这个约定让后面的函数写起来很轻。比如check_device_state先调run_command(['adb','devices']),只要返回码不是0,就不必再判断输出内容;flash_partition在重试循环里也只看返回码是不是0,非0就打印stderr并等待2秒再试。需要留意的是,返回码为0只代表命令进程退出码为0,不代表业务一定成功。比如fastboot devices在没设备时也可能返回0,只是输出为空,所以状态检测还要看stdout内容。
2.3 超时30秒与重试3次的取舍
TIMEOUT=30这个值不是拍脑袋来的。adb和fastboot的短命令如果30秒还没返回,大概率不是“再等等就好”,而是设备没进到正确模式、USB协商失败或者驱动层卡住。这时候继续等只会拖长脚本执行时间,不如直接超时返回,让调用方打印错误。真遇到大镜像刷写慢的情况,应该单独给那条命令传更大的timeout,而不是把全局值无脑调到几分钟。
MAX_RETRIES=3只用在flash_partition里。刷写分区失败有时是瞬时的:USB口供电波动、设备刚切换模式还没稳定、fastboot服务端还没完全就绪。重试两次往往能过,但重试太多次会掩盖真正的问题,比如镜像本身损坏或者分区表不匹配,刷十次也不会成功。3次是一个折中:给瞬时故障留两次机会,第三次失败就退出,让操作者去看stderr。
这里还有一个容易忽略的细节:重试之间用time.sleep(2)而不是立刻重试。fastboot flash失败后,设备可能还处在半通信状态,立刻再发命令容易连续失败;停2秒让USB栈和fastboot进程缓一下,成功率会高一些。解锁函数没有加重试,因为fastboot flashing unlock会清数据,重复发命令没有意义,而且部分厂商需要用户在屏幕上确认,脚本盲目重试只会把等待时间拉长。
3. 代码开发工具的设备状态识别:ADB、Fastboot与EDL的判定边界
3.1 adb devices输出解析与“device”关键字
设备状态识别是整个脚本的路由器:设备在ADB模式,就尝试重启到bootloader;已经在Fastboot模式,就直接往下刷;两边都检测不到,就报无设备。check_device_state先跑adb devices,再跑fastboot devices,顺序不能反。因为设备在Fastboot模式下adb devices通常为空,先查adb不会误判;反过来如果先查fastboot,在ADB模式下fastboot devices也可能返回空,逻辑上也能走通,但先ADB更符合“从系统内发起切换”的常见路径。
python复制def check_device_state():
"""
检测当前设备连接状态。
:return: 'adb', 'fastboot', 'edl', 'unknown', 'none'
"""
# 检测ADB设备
code, out, err = run_command(['adb', 'devices'])
if code == 0 and out:
lines = out.splitlines()
if len(lines) > 1 and 'device' in lines[1]:
return 'adb'
# 检测Fastboot设备
code, out, err = run_command(['fastboot', 'devices'])
if code == 0 and out:
if out.strip():
return 'fastboot'
# 检测EDL模式(高通9008端口,需依赖lsusb或设备管理器,此处简化为Fastboot检测)
# 实际项目中可通过pyusb库检测VID:PID 05c6:9008
return 'none'
adb devices的输出第一行通常是“List of devices attached”,第二行开始才是设备列表。代码里用lines[1]取第二行,再判断里面有没有device关键字。这个写法对单设备场景够用,但边界很明显:如果输出第二行是“unauthorized”或者“offline”,就不会返回adb;如果同时连了两台设备,lines[1]只代表第一台。实际使用时,如果脚本返回none但手机屏幕上已经弹出USB调试授权框,先看adb devices的输出是不是unauthorized,授权后再跑一次。这个限制在排错章节会展开。
3.2 fastboot devices的判定与模式切换
fastboot devices的输出比adb devices简单,通常一行一个序列号,没有设备时输出为空。代码里用if out.strip()判断,只要去掉空白后还有内容,就认为有Fastboot设备。这里没有去解析序列号,因为脚本的目标是“有没有设备”,不是“是哪台设备”;批量场景下如果需要指定设备,再在命令里加-s参数,那是另一层逻辑。
从ADB切到Fastboot的动作放在主流程里,不在check_device_state里做。主流程检测到state == 'adb'后,执行adb reboot bootloader,然后time.sleep(5),再重新检测。5秒是经验值,大部分设备重启到bootloader在3到5秒内完成,但有的机型慢一些,5秒后仍可能返回none。这时候脚本会提示“Device is not in fastboot mode. Please enter fastboot manually.”,而不是死循环等待。把切换动作和状态检测分开,好处是check_device_state保持只读,不会因为调用一次检测就改变设备状态,调试时更安全。
3.3 EDL模式为什么只留注释
代码里EDL分支只有注释,没有实现。注释写明高通9008端口需要依赖lsusb或设备管理器,实际项目中可以通过pyusb检测VID:PID 05c6:9008。这里不展开实现,是因为EDL模式下的操作和fastboot完全不是一套命令,而且不同芯片平台进入EDL的方式差异很大,硬塞进这个脚本会让函数职责变混。当前脚本只覆盖ADB和Fastboot两种日常模式,EDL检测留作扩展点。
这个取舍对使用者有实际影响:如果设备已经进入EDL,check_device_state会返回none,主流程会报“No device detected. Please connect device and enable USB debugging.”。看到这个提示不要以为设备坏了,先确认是不是进了9008模式。如果确实需要EDL操作,应该单独写检测函数,而不是改check_device_state的判断顺序。把边界写清楚,比假装支持所有模式更可靠。
4. 代码开发工具的刷写封装:解锁、分区写入与重试循环
4.1 unlock_bootloader的前置状态检查与数据清除提醒
解锁函数第一件事不是发命令,而是再调一次check_device_state,确认设备在fastboot模式。如果不在,直接打印错误并返回False。这个重复检测看起来多余,但主流程里设备可能刚从ADB切过来,状态并不稳定;解锁又是会清数据的重操作,宁可多查一次,也不要在错误模式下发命令。
python复制def unlock_bootloader():
"""
解锁Bootloader。注意:此操作会清除所有数据。
"""
state = check_device_state()
if state != 'fastboot':
print("[ERROR] Device is not in fastboot mode.")
return False
print("[INFO] Attempting to unlock bootloader...")
code, out, err = run_command(['fastboot', 'flashing', 'unlock'])
if code == 0:
print("[SUCCESS] Bootloader unlock command sent. Check device screen for confirmation.")
return True
else:
print(f"[ERROR] Unlock failed: {err}")
return False
命令用的是fastboot flashing unlock,不是fastboot oem unlock,两者在不同厂商设备上支持情况不一样,脚本只按前者写。返回码为0只代表命令发送成功,不代表解锁一定完成;部分设备需要用户在屏幕上再按一次确认,所以成功提示写的是“Check device screen for confirmation.”。另外,这个函数没有加重试,因为解锁失败通常不是瞬时通信问题,而是设备策略不允许或需要解锁码,重复发命令没有意义。调用方在主流程里默认把解锁注释掉了,需要时再打开,这个默认值是有意为之:解锁会清除所有用户数据,自动执行风险太高。
4.2 flash_partition的路径校验、循环重试与失败退出
分区刷写函数先检查镜像文件是否存在,不存在直接返回False,不进入重试循环。这个顺序很重要:如果路径写错,重试3次只是浪费6秒,还会打印三次同样的错误。检查通过后再进入for循环,每次调fastboot flash,失败就打印WARN并sleep 2秒,最多3次。
python复制def flash_partition(partition, image_path):
"""
刷写指定分区。
:param partition: 分区名,如 'boot', 'system'
:param image_path: 镜像文件路径
"""
if not os.path.exists(image_path):
print(f"[ERROR] Image file not found: {image_path}")
return False
print(f"[INFO] Flashing {partition} from {image_path}...")
for attempt in range(MAX_RETRIES):
code, out, err = run_command(['fastboot', 'flash', partition, image_path])
if code == 0:
print(f"[SUCCESS] {partition} flashed successfully.")
return True
else:
print(f"[WARN] Attempt {attempt + 1} failed: {err}")
time.sleep(2)
print(f"[ERROR] Failed to flash {partition} after {MAX_RETRIES} attempts.")
return False
参数partition直接拼进命令列表,不经过字符串拼接,所以分区名里就算有特殊字符也不会被shell解释。image_path用os.path.exists判断,相对路径以脚本运行时的工作目录为基准,这是一个后面排错会反复出现的点。重试循环里打印的是err而不是out,因为fastboot失败信息通常在stderr里。第三次失败后函数返回False,主流程收到False会打印FATAL并退出,不会继续刷后面的分区。这个“失败即停”策略避免了一个分区没写进去、后面的分区却继续写,最后设备状态更乱。
4.3 main函数的编排:检测、切换、刷写、清数据、重启
主流程把前面几个函数串起来,顺序是检测设备、必要时从ADB切到Fastboot、按字典顺序刷写分区、清数据、重启。刷写字典里放了boot、vbmeta、system三个示例分区,路径指向./images/。这个字典就是使用者要改的地方,换成自己镜像的实际路径。
python复制def main():
print("=== Android Flash Automation Tool ===")
# 1. 检测设备
state = check_device_state()
print(f"[INFO] Current device state: {state}")
if state == 'none':
print("[ERROR] No device detected. Please connect device and enable USB debugging.")
sys.exit(1)
if state == 'adb':
print("[INFO] Device in ADB mode. Rebooting to bootloader...")
run_command(['adb', 'reboot', 'bootloader'])
time.sleep(5)
state = check_device_state()
if state != 'fastboot':
print("[ERROR] Device is not in fastboot mode. Please enter fastboot manually.")
sys.exit(1)
# 2. 解锁Bootloader(可选,根据需求注释)
# unlock_bootloader()
# time.sleep(10) # 等待用户确认
# 3. 刷写分区(示例:刷写boot与vbmeta)
images = {
'boot': './images/boot.img',
'vbmeta': './images/vbmeta.img',
'system': './images/system.img'
}
for partition, path in images.items():
if not flash_partition(partition, path):
print(f"[FATAL] Failed to flash {partition}. Aborting.")
sys.exit(1)
# 4. 清除数据
wipe_data()
# 5. 重启
reboot_system()
print("=== Flash Process Completed ===")
主流程里解锁被注释掉,这是一个安全默认值:先让使用者确认镜像路径和分区名,再手动打开解锁。从ADB切Fastboot后固定等5秒,如果设备慢,5秒后check_device_state仍返回none,脚本会退出并提示手动进入Fastboot,而不是继续傻等。刷写循环按字典插入顺序执行,Python 3.7以上字典保持插入顺序,所以boot、vbmeta、system的先后是确定的。清数据和重启放在所有分区成功之后,避免刷一半就清数据导致设备无法恢复。
wipe_data和reboot_system函数本身很短,前者调fastboot -w,后者调fastboot reboot。fastboot -w会清除用户数据和缓存,执行前脚本没有二次确认,因为主流程已经要求操作者确认镜像路径;如果要把这个脚本交给别人用,建议在wipe_data前加一个input确认,这是使用习惯问题,不是脚本本身的缺陷。
5. 代码开发工具避坑排查:五个现场与现象到解决的路径
5.1 环境与连接类问题
现象一:脚本一运行就打印“Command not found. Please install platform-tools.”,返回码-2。
原因:run_command捕获到FileNotFoundError,说明系统PATH里找不到adb或fastboot。常见情况是platform-tools下载后放在某个目录,但没有加入环境变量,或者脚本没有和platform-tools放在同一目录。
解决:把platform-tools目录加入系统环境变量,或者把脚本复制到platform-tools目录下再运行。验证方法是先在终端里直接执行adb devices和fastboot devices,能出输出再跑脚本。不要改run_command去忽略这个错误,因为命令不存在时后面的状态检测全是空转。
现象二:手机已经连上USB并开了调试,脚本check_device_state却返回none。
原因:adb devices的输出第二行可能是unauthorized或offline,而check_device_state只认包含device关键字的第二行。unauthorized通常意味着手机屏幕上还有授权弹窗没点允许;offline可能是adb服务进程状态异常。
解决:先在终端执行adb devices,看第二行到底是device、unauthorized还是offline。unauthorized就在手机上点允许;offline可以尝试adb kill-server再adb devices。如果同时连了多台设备,lines[1]只代表第一台,需要拔掉其他设备或改用序列号指定。
现象三:主流程检测到ADB后自动重启到bootloader,但5秒后仍提示“Device is not in fastboot mode.”。
原因:adb reboot bootloader命令返回成功只代表重启指令发出,设备实际进入Fastboot的时间受机型和USB枚举速度影响,5秒不一定够;也有可能是设备重启后驱动重新加载,fastboot devices需要更久才能看到设备。
解决:先手动执行fastboot devices确认是否已经进入Fastboot。如果确实进了但脚本没检测到,把time.sleep(5)调大到8或10秒;如果一直进不去,检查USB线是否只支持充电、换一个USB口,或者手动按组合键进入Fastboot。不要在主流程里写while True无限等待,否则设备没进Fastboot时脚本会卡死。
5.2 刷写与重试类问题
现象四:flash_partition打印“Image file not found”,但镜像文件明明存在。
原因:images字典里写的是相对路径./images/boot.img,os.path.exists以脚本运行时的工作目录为基准。如果从别的目录执行python flash_tool.py,工作目录不是脚本所在目录,相对路径就找不到文件。
解决:把images字典里的路径改成绝对路径,或者在运行脚本前先cd到脚本所在目录。也可以在使用说明里写清楚“请在脚本目录下执行”。这个问题在重试循环之前就会暴露,不会浪费3次刷写时间,但提示信息只有路径,容易让人以为是文件名拼错。
现象五:某个分区连续失败3次,脚本打印FATAL后退出,设备停在Fastboot界面。
原因:MAX_RETRIES=3,三次fastboot flash都返回非0。常见原因包括镜像文件损坏、分区名与设备不匹配、USB连接在刷写过程中断开。脚本失败即停,不会自动回滚,所以设备会停在Fastboot,但不会变砖。
解决:先看每次WARN打印的stderr,如果是“Partition not found”就检查分区名;如果是传输错误,换线换USB口,确认镜像哈希值后再试。可以先用单条fastboot flash boot ./images/boot.img手动刷一个分区,确认命令本身能过,再跑脚本。不要盲目把MAX_RETRIES调到10,重试太多次会掩盖镜像损坏这类硬问题。
现象六:run_command返回-1超时,但fastboot flash其实还在后台跑。
原因:subprocess.run设置timeout后,超时会杀掉子进程并抛出TimeoutExpired,脚本返回-1。如果刷写大镜像确实需要超过30秒,就会误判为失败。
解决:给flash_partition里的run_command单独传更大的timeout,比如run_command(['fastboot','flash',partition,image_path], timeout=120),而不是改全局TIMEOUT。同时确认USB连接稳定,大镜像刷写中途断开也会表现为超时。超时后不要立刻重复刷同一个分区,先fastboot devices确认设备还在,再决定是否重试。
6. 代码开发工具的验证习惯:分阶段跑通与参数调优
这类脚本最忌讳一上来就跑完整main。我的习惯是分三段验证:先只跑check_device_state,确认ADB和Fastboot两种模式都能正确识别;再单独调flash_partition刷一个最小的分区,看路径和重试逻辑是否正常;最后才跑main,并且把解锁函数保持注释,确认刷写和重启链路没问题后再决定要不要打开解锁。分阶段验证能把问题定位在单个函数里,而不是等完整流程失败后从头猜。
| 验证阶段 | 执行内容 | 通过标准 | 常见失败点 |
|---|---|---|---|
| 第一阶段 | check_device_state | ADB模式返回adb,Fastboot模式返回fastboot,拔线返回none | 授权未确认、多设备只读第一行 |
| 第二阶段 | flash_partition单分区 | 镜像存在时能刷入并返回True,路径错时立刻返回False | 相对路径、镜像损坏、分区名错 |
| 第三阶段 | main完整流程 | 从ADB切Fastboot成功,分区按顺序刷完,清数据后重启 | 切换等待时间不够、某个分区失败即停 |
参数调优只动两个地方:TIMEOUT和MAX_RETRIES。短命令超时优先查连接,不要先调大TIMEOUT;刷写重试优先查镜像和线材,不要先调大MAX_RETRIES。如果确实要刷大镜像,用函数参数单独放大timeout,保留全局30秒作为短命令的保险。还有一点,images字典里的路径最好在运行前打印出来,让操作者看一眼再按回车,比失败后翻日志快得多。
从那以后我每次写这类设备管理脚本,都会先把check_device_state和run_command的返回值打印出来,确认状态和错误码再往下走,不再一股脑从解锁刷到重启。希望帮到你。
