1. 解压即用的代码开发工具:platform-tools.zip 先解决哪三个问题
手里只有一台没装任何移动开发环境的 Windows 机器,却要给设备装个包、抓一份崩溃日志、把日志文件拉回本地——这种时候最省事的做法不是装一整套 IDE,而是解压一个 platform-tools.zip,直接调用 adb.exe 和 fastboot。这类代码开发工具本质上是平台工具集:核心就是 adb、fastboot,加上它们依赖的一组动态库,承担设备识别、应用安装、日志抓取、文件互传、分区刷写这几件基础活。它适合三类人:不想为一次调试装整套环境的开发者、要批量处理多台设备的测试人员、以及设备开不了机只能靠命令行抢救数据的运维。下面按解压、路径、握手、命令、排错一路走。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 把 platform-tools 放进开发工具链:解压路径、环境变量与版本冲突
2.1 压缩包里到底有什么,哪些文件不能单独拿走
解压 platform-tools.zip 之后,得到的是一个扁平目录,不是安装程序,也没有安装向导。目录里能看到 adb.exe、fastboot.exe,以及同级的几个动态库文件,Windows 下最典型的是 AdbWinApi.dll 和 AdbWinUsbApi.dll,前者负责进程间那层 API 适配,后者负责 USB 底层枚举。macOS 和 Linux 版本则是无扩展名的 adb、fastboot 可执行文件,解压后还要补一个可执行权限。
这里第一个容易翻车的地方是:不少人图省事,只把 adb.exe 单独复制到某个顺手的位置,然后双击或者丢进 PATH。结果一运行就弹窗提示缺少 AdbWinApi.dll,或者命令行里直接报「无法启动此程序,因为计算机中丢失 AdbWinApi.dll」。原因不复杂——adb.exe 启动时会去自己所在目录找同级的依赖库,你把 exe 搬走、库留在压缩包里,它自然起不来。
所以规则很简单:整个目录一起搬,一个文件都别落下。搬运的时候用复制粘贴整目录,不要用「只解压需要的文件」。如果你习惯用命令行解压,注意别让解压工具在目标目录里再套一层同名目录,最后形成 platform-tools/platform-tools/adb.exe 这种两层结构,后面的环境变量一定会配错。
2.2 解压路径怎么选:为什么不能放桌面和 Program Files
路径这件事看起来无关紧要,实际上是后面一大半「命令找不到」和「刷写没权限」的根源。我把常见的几类错误位置和后果列一下:
| 放置位置 | 表面上看 | 实际问题 |
|---|---|---|
| 桌面 | 好找 | 桌面常被清理工具扫,路径里常带用户名和空格 |
| 下载目录 | 解压方便 | 容易被磁盘清理、被同名压缩包覆盖 |
| Program Files | 看起来正规 | 写入需要管理员权限,更新时覆盖麻烦 |
| 中文路径 | 无所谓 | 部分脚本和批处理对中文路径处理不干净 |
固定短路径(如 C:\platform-tools) |
需要手动建 | 路径稳定、无空格、权限明确 |
我的习惯是固定一个短路径,Windows 上直接 C:\platform-tools 或者 D:\tools\platform-tools,macOS/Linux 上放到用户目录下统一的一个 tools 目录里。这样做的好处是:所有脚本里写全路径时不用加引号,不会因为路径里有空格把参数截断;升级时直接把新压缩包解压覆盖旧目录,环境变量一个字都不用改。
提示:解压完之后先在文件管理器里点进目录确认一次,看到的应该是 adb.exe 直接躺在当前层,而不是还要再点一层目录才看到它。
2.3 环境变量与版本冲突:where adb 只应该有一条输出
确认目录结构没问题,再把目录本身加进 PATH,注意加的是目录,不是 adb.exe 的完整路径。Windows 上在系统属性里找到环境变量,编辑 Path,新建一条填目录;macOS/Linux 上在 shell 配置文件里追加一行 export,把目录前置或追加进去。改完之后必须重开一个终端窗口,老窗口里读的还是旧环境。
接下来是关键一步:确认系统到底解析到哪一个 adb。Windows 用 where adb,macOS/Linux 用 which -a adb。如果输出只有一条,并且指向你刚放的那个目录,说明干净;如果输出两条以上,说明机器上还有别的 adb,常见来源是 IDE 自带的、模拟器自带的、某些工具链里捆的。
多个 adb 共存会带来一个很隐蔽的问题:adb 的服务端进程是单例的。第一个 adb 启动后会在后台拉起一个 server,后面再来一个不同版本的 adb 客户端,它会发现已有 server 版本对不上,于是把旧 server 杀掉、自己重新拉一个,终端上就会刷出类似 adb server version doesn't match this client; killing... 的提示。单次看只是多一行日志,但在脚本里连续调用时,server 被反复杀掉重建,设备状态会短暂丢失,表现为命令时好时坏,非常像玄学。
bash复制# Windows:确认解析到哪一个 adb(cmd 或 PowerShell 都可以)
where adb
# macOS / Linux:-a 表示列出所有命中项,而不是只显示第一个
which -a adb
# 清掉当前 server,再用当前这个 adb 重新拉起
adb kill-server
adb start-server
adb version
where 和 which -a 的作用是把所有候选列出来,只看第一条等于自欺欺人。kill-server 结束后台的 daemon 进程,start-server 用当前这个二进制重新拉起,adb version 输出里的版本行用来确认你现在用的到底是哪一个。如果你确实需要保留多个版本,那就别指望 PATH 顺序,直接在脚本里写全路径调用,谁也别抢谁的 server。
2.4 第一次验证:三条命令确认工具链可用
环境配完不要急着插设备,先在没有任何设备连接的情况下跑一遍自检。顺序是:先 adb version 看二进制能不能正常执行,再 adb start-server 看 server 能不能拉起来,最后 adb devices 看列表输出格式是否正常。这三步都不需要设备参与,任何一步报错都说明是工具链本身的问题,而不是设备或线的问题。
这个顺序的价值在于把问题分层。很多人一上来就插设备,看到 adb devices 是空列表,就开始怀疑驱动、怀疑线、怀疑设备,实际上可能只是 PATH 里那条记录写成了 adb.exe 全路径导致命令根本没法解析。先做无设备的自检,能把工具链问题和连接问题彻底分开,省下的时间比想象中多。
3. adb 握手三件事:设备识别、授权弹窗与四种连接状态
3.1 打开 USB 调试:握手的前置条件
设备这边有两个开关必须先打开:开发者选项本身,以及开发者选项里的 USB 调试。不同设备进入开发者选项的方式不一样,通常是连续点几次版本号,这里不展开。打开之后还有一个容易忽略的点:连接模式。很多设备插上电脑默认是「仅充电」,这个模式下部分机型不会把调试接口暴露出来,需要在下拉通知里把连接方式切成文件传输。
Windows 上还有一层驱动。近几年的系统对多数设备是免驱的,老设备或者特殊芯片的平台可能需要单独装厂商提供的驱动,否则设备管理器里会出现一个带感叹号的未知设备,adb devices 自然是空的。判断方法很直接:插上设备看设备管理器有没有异常项,有就先解决驱动,别在命令行里反复试。
3.2 adb devices 的四种输出分别意味着什么
握手成不成功,全看 adb devices 这一行输出。它的状态不多,但每一种对应的原因完全不同,混着猜很容易走弯路:
| 输出状态 | 含义 | 常见原因 |
|---|---|---|
只有 List of devices attached,下面空白 |
完全没识别到设备 | 线只供电、调试没开、驱动缺失、USB 口异常 |
unauthorized |
设备认到了,但没授权这台电脑 | 授权弹窗没点、点了拒绝、之前勾过不再提示 |
offline |
设备在列表里,但通道不可用 | server 与设备端状态不同步、进程卡住、线材接触不良 |
device |
正常可用 | 无 |
加 -l 参数会多输出型号和传输方式等信息,多设备环境下靠它拿序列号。序列号是后面所有 -s 参数的依据,先拿到再谈别的。
offline 这个状态值得单独说一句,因为它最像「设备坏了」。实际上绝大多数 offline 都是 server 侧的问题,设备本身好好的。处理顺序是:先 adb kill-server 再 adb start-server,让 server 重新和设备握手;不行就换一根线、换一个口;再不行在开发者选项里把 USB 调试关掉再打开,让设备侧重置一次调试通道。
3.3 授权与重连:unauthorized 的正规处理
第一次把设备连到一台新电脑上,设备屏幕会弹一个 RSA 指纹确认框,问是否允许这台电脑进行 USB 调试。点允许,状态才会从 unauthorized 变成 device。框上通常还有一个「始终允许来自这台计算机」的勾选项,勾上之后下次不再问。
翻车场景通常是这几种:弹窗弹出来的时候人不在电脑前,超时自动取消了;手滑点了拒绝;或者之前勾了始终允许,后来因为某种原因想换一台电脑用,结果新电脑一直卡在 unauthorized。对应的处理动作也不一样:
- 弹窗没点:拔掉重插,弹窗会再次出现。
- 点了拒绝:进开发者选项,找到「撤销 USB 调试授权」,撤销之后重插,弹窗会重新来。
- 一直不弹窗:先
adb kill-server再重连;仍然不弹,才考虑清掉用户目录下.android文件夹里的 adbkey 文件,让本机重新生成一对密钥,代价是所有已授权设备都要重新点一次允许。
最后这个动作相当于后悔药,能不用就不用,因为一旦删了密钥,之前所有信任过这台电脑的设备全部失效,得一个个重新授权。我一般把它放在排查链条的最末端,前面几步都确认无效了再动。
3.4 多设备与日常五条命令
测试机上同时插三五台设备是常态,这时候所有命令都要带 -s <序列号>,不带就会报 more than one device/emulator 直接退出。序列号从 adb devices -l 里拿,复制粘贴别手打,设备序列号里常有容易看错的字符。
bash复制# 列出设备,带型号与传输方式,用来拿序列号
adb devices -l
# 安装调试包:-r 覆盖安装,-d 允许版本降级
adb -s <serial> install -r app-debug.apk
# 抓日志到本地文件:-v time 让每行带时间戳
adb -s <serial> logcat -v time > device.log
# 把设备上的崩溃日志拉回本地
adb -s <serial> pull /sdcard/crash.log ./crash.log
# 把本地配置推到设备
adb -s <serial> push ./config.ini /sdcard/config.ini
-s 后面接的就是序列号,多设备时它是必需项,单设备时可以省略。install 的 -r 表示保留数据覆盖安装,-d 表示允许安装比设备上更低版本的同名包,调试阶段这两个参数用得最多。logcat 的 -v time 只是时间戳格式选项,配合 > 把输出重定向到文件,比在终端里滚动翻找靠谱得多。pull 和 push 的方向别记反:pull 是从设备往本地拿,push 是从本地往设备送。
除了这五条,adb shell 用来进设备命令行,adb reboot 用来重启设备,adb reboot bootloader 用来切到下一章要讲的 fastboot 模式。这些命令本身没什么花哨的,真正决定效率的是前面的握手是否稳定——握手不稳,后面每一条命令都会时灵时不灵。
4. fastboot 刷写链路:从 reboot bootloader 到分区写入
4.1 进入 bootloader 与 fastboot devices
fastboot 和 adb 是两个不同的工作模式,设备必须先切到 bootloader 才能被 fastboot 识别。切换命令是 adb reboot bootloader,执行后设备重启,屏幕上通常会出现一行 fastboot 相关的字样,有的设备是黑底白字,有的是一块极简界面。看到这个界面,才说明设备真的进了 bootloader,而不是单纯黑屏。
进模式之后,第一件事不是刷,而是 fastboot devices 确认能看见设备。这条命令和 adb devices 长得像,但走的是完全不同的 USB 通道,用到的驱动也不是同一套。Windows 上经常出现 adb 能看见、fastboot 看不见的情况,原因就在这里:驱动装的是 adb 那套,bootloader 模式下设备换了个硬件 ID,系统没认出来。
如果 fastboot devices 是空的,按这个顺序排查:确认屏幕上是 bootloader 界面而不是关机状态;换一个 USB 口,优先用 USB 2.0 的口,某些平台在 3.0 口上 bootloader 枚举不稳;换一根数据线,劣质线在系统模式下能用,在 bootloader 模式下掉链子;最后才是补驱动。
4.2 flash 命令的语法与分区名
fastboot 的核心动作就一个:把本地镜像写到设备的某个分区上。语法是 fastboot flash <分区名> <镜像文件>,两个参数都必须和设备对得上,写错任何一个都可能出问题。
bash复制# 从系统切到 bootloader
adb reboot bootloader
# 确认 fastboot 能看到设备,输出应带序列号
fastboot devices
# 查看设备变量与分区信息,部分设备支持
fastboot getvar all
# 写入单个分区,分区名与镜像必须一一对应
fastboot flash boot boot.img
# 写完重启回系统
fastboot reboot
getvar all 不是所有设备都支持,支持的话会把分区表、版本、解锁状态等变量全列出来,是确认分区名最稳的方式。flash 后面第一个参数是分区名,常见的有 boot、recovery、system、vendor 这类,但具体有哪些分区、每个分区叫什么,完全由设备决定,不要照着别的机型抄。第二个参数是本地镜像路径,路径带空格时要用引号包住。
fastboot reboot 是刷完回系统的正常出口,另外还有 fastboot reboot-bootloader,用于刷完某个分区后继续停留在 bootloader 里接着刷下一个。连续刷多个分区时用后者能少一次来回切换。
4.3 解锁状态与写入失败的典型返回
刷写失败的原因里,解锁状态占了一大半。设备出厂默认是锁定状态,锁定状态下 fastboot 会拒绝任何写入操作,返回类似 FAILED (remote: 'not allowed in locked state') 或者 Flashing is not allowed in Lock State 的信息。看到这类返回,不要去改命令参数,问题不在命令上。
解锁命令本身也分两套:新一些的设备用 fastboot flashing unlock,老设备用 fastboot oem unlock,具体哪条有效取决于设备实现。执行解锁时设备屏幕上通常还会有一次确认操作,需要在设备上手动确认,光敲命令不够。
注意:解锁会清空设备上的用户数据,这一步没有撤销。刷写之前先想清楚设备上有没有必须保留的东西。
其它几类典型返回也顺手记一下:cannot load 'xxx.img' 表示本地文件路径不对或者文件不存在,先确认当前目录;waiting for device 长时间卡住,说明 fastboot 根本没连上设备,回到上一节查驱动和线;FAILED (remote: 'partition table doesn't exist') 基本就是分区名写错了,用 getvar all 对一遍。
4.4 刷完之后的收尾动作
fastboot reboot 之后设备会重启,第一次开机通常比平时慢,因为系统在做校验和初始化,这个阶段不要因为等不及就断电。如果重启后卡在开机动画不动,先回想刚才刷的是哪个分区、镜像和设备型号是否匹配,多数情况是刷错了镜像或者刷了一个不完整的分区。
我的习惯是刷之前先确认两件事:设备型号和镜像是不是一对,以及原分区的镜像有没有留底。留底这件事在能正常进系统的时候做最省事,进了 bootloader 再想备份就麻烦得多。刷写本身是几秒钟的事,真正花时间的是刷错之后的恢复。
5. adb 与 fastboot 的避坑清单:五类翻车现场的现象、原因与解决
5.1 命令提示「adb 不是内部或外部命令」
现象:在 cmd 或 PowerShell 里敲 adb,直接返回「不是内部或外部命令,也不是可运行的程序」。
原因有三种:PATH 里根本没加这一条;加进去了但填的是 adb.exe 的完整路径而不是目录;加完没有重开终端,当前窗口读的还是旧环境。
解决:先跑 where adb 看有没有输出。没输出就去检查 PATH 条目,确认填的是目录本身。有输出但指向别处,说明顺序被别的版本顶掉了。改完之后关掉当前终端重新开一个,别在旧窗口里反复试。
5.2 一运行就报缺少 AdbWinApi.dll
现象:adb.exe 能双击,但一执行就弹窗提示缺少 AdbWinApi.dll,或者命令行里直接退出。
原因:只把 adb.exe 单独复制出来了,同级的动态库没跟着走。adb 启动时会去自己所在目录找依赖库,找不到就起不来。
解决:把整个 platform-tools 目录一起搬,不要拆开。已经拆散的,重新解压一份完整目录,用整目录替换掉之前那个孤零零的 exe。这个问题没有别的绕法,缺库就是缺库。
5.3 adb devices 列表是空的
现象:输出只有 List of devices attached 这一行,下面什么都没有,设备屏幕也没有任何反应。
原因:数据线只供电不传数据;USB 调试没开;连接模式停在「仅充电」;Windows 上驱动没装好;USB 口本身有问题。
解决:按成本从低到高排——先换一根确定能传数据的线,再换一个 USB 口,然后在设备上把连接模式切成文件传输,接着确认 USB 调试开关是打开的,最后去设备管理器看有没有带感叹号的未知设备。这条链路走完还不行,再考虑驱动问题。
5.4 状态卡在 unauthorized
现象:adb devices 能看到设备,但状态是 unauthorized,任何需要设备配合的命令都报 device unauthorized。
原因:授权弹窗没被确认,或者之前点过拒绝,或者勾了「始终允许」但后来密钥对不上了。
解决:拔插一次触发弹窗;弹不出来就进开发者选项撤销 USB 调试授权再重连;仍然不行才清 .android 目录下的 adbkey 重新生成。删密钥是最后手段,因为它会让所有已授权设备一起失效。
5.5 fastboot devices 空白,但 adb 明明是好的
现象:adb devices 正常显示 device,执行 adb reboot bootloader 之后屏幕也进了 bootloader,但 fastboot devices 什么都没有。
原因:fastboot 走的是另一套 USB 通道和驱动,adb 那套驱动在 bootloader 模式下不生效;也可能是 USB 3.0 口在 bootloader 阶段枚举不稳;还有一种是设备其实没真正进 bootloader,只是黑屏。
解决:先看屏幕有没有 fastboot 字样确认模式;换 USB 2.0 口;换线;补 bootloader 模式对应的驱动。这四步里,换口和换线解决的比例比想象中高,别一上来就折腾驱动。
6. 把命令行开发工具收进脚本:固化动作与上线前验证清单
单次调试靠手敲命令没问题,但要反复给多台设备装包、抓日志,手敲就会漏参数、会记错序列号。我一般会把入口收敛成一个脚本,所有动作都从这一个入口走,脚本先做自检再执行具体命令,这样每次跑之前环境状态是已知的。
bash复制#!/usr/bin/env bash
# adb-run.sh:统一入口,先自检再执行,避免用到 PATH 里的野生版本
set -euo pipefail
ADB_BIN="${ADB_BIN:-adb}" # 允许用环境变量指定某个具体的 adb
SERIAL="${SERIAL:-}" # 为空表示不指定设备,多设备时命令会自己报错
echo "== 自检 =="
"$ADB_BIN" version
"$ADB_BIN" kill-server
"$ADB_BIN" start-server
"$ADB_BIN" wait-for-device
"$ADB_BIN" devices -l
if [ -n "$SERIAL" ]; then
TARGET=(-s "$SERIAL")
else
TARGET=()
fi
# 抓一份当前日志并落盘,-d 表示抓完立即退出而不是一直挂着
"$ADB_BIN" "${TARGET[@]}" logcat -d -v time > "log-$(date +%Y%m%d-%H%M%S).txt"
set -euo pipefail 这三项分别管:命令失败立即退出、引用未定义变量报错、管道里任何一段失败都算失败。少了它,脚本中途出错还会继续往下跑,最后拿到一份看起来正常其实缺数据的日志。ADB_BIN 用环境变量兜底,需要指定版本时不用改脚本。wait-for-device 会阻塞到设备可用为止,比手动 sleep 靠谱。logcat -d 抓完即退,避免脚本卡住不退。
Windows 上更喜欢用批处理,关键是别依赖 PATH:
bat复制@echo off
rem 固定使用本目录的 adb.exe,避免被 PATH 里其它版本顶掉
set "ADB=%~dp0adb.exe"
"%ADB%" kill-server
"%ADB%" start-server
"%ADB%" devices -l
%~dp0 取的是批处理文件所在目录,这样脚本跟着 platform-tools 目录一起走,拷到哪台机器都能直接用。这套写法解决的就是前面提到的版本冲突:不查 PATH,不猜顺序,用哪个版本由脚本位置决定。
日常动手前,我会按下面这张表过一遍,五分钟不到,能挡掉大部分低级问题:
| 顺序 | 检查项 | 命令 | 通过标准 |
|---|---|---|---|
| 1 | 解析到正确的 adb | where adb / which -a adb |
只有一条且指向目标目录 |
| 2 | server 状态干净 | adb kill-server + start-server |
无版本不匹配提示 |
| 3 | 设备可识别 | adb devices -l |
状态为 device |
| 4 | 读写通道正常 | adb push + adb pull |
文件大小与内容一致 |
| 5 | bootloader 可达 | adb reboot bootloader + fastboot devices |
输出带序列号 |
血泪经验是第 4 步别省。设备状态显示 device 不等于文件通道就通,曾经有一次推上去的配置文件大小对不上,排查了半天以为是设备端解析问题,最后发现是推的时候设备存储满了。先做一次小文件往返,能提前暴露这类问题。从那以后我每次换机器、换线、换设备,都强制把这张表走一遍再动手,省下来的返工时间远超这五分钟。希望帮到你。
