1. 解压完却敲不出 adb:先分清是工具没到位还是入口没接对
platform-tools 这套代码开发工具,解压完并不等于能用。我见过最常见的现场是:压缩包解压到桌面,终端里敲 adb devices,回来的不是设备列表,而是一句 command not found;换个人接手,命令能敲出来了,列表却是空的。两种现象看着都像“工具坏了”,实际一个出在路径,一个出在设备状态。platform-tools 本身是免安装的 adb 与 fastboot 命令行集合,用来连设备、装包、看日志、进 bootloader 刷分区,适合刚接手调试环境的开发者、需要重复刷机的测试人员,以及想把 adb 塞进自动化脚本的人。下面按我实际排问题的顺序,从目录、PATH、三态输出一路写到 fastboot 刷写和几个反复踩的坑。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 落地位置与 PATH:代码开发工具装在哪,决定后面顺不顺
platform-tools 跟一般需要安装程序的工具不一样,它就是一个压缩包,解压到哪都能跑。也正因为“哪都能跑”,位置反而成了第一道分水岭:放对了,后面 adb devices、fastboot devices 一路顺;放错了,报错信息往往指向别处,让人在设备和驱动上白折腾半天。这一章先把目录层级、路径命名、环境变量和可执行权限这四件事一次做对。
2.1 解压层级:多套一层 platform-tools 是最常见的翻车
很多人解压时习惯右键“解压到当前文件夹”,结果落地目录变成 platform-tools/platform-tools/,adb 二进制在实际的内层,PATH 却指到了外层。命令敲下去,系统在外层目录里找不到 adb.exe,报的还是“命令找不到”,于是有人开始怀疑压缩包损坏、怀疑系统权限,就是不怀疑层级。
我一般固定一个目录,Linux/macOS 用 /opt/android/platform-tools,Windows 用 C:\android\platform-tools。解压时直接把目标目录写进命令,少一次 cd,也少一次搞错层级的机会。
bash复制# Linux / macOS:解压到指定目录,-d 决定落地位置
mkdir -p /opt/android
unzip -o platform-tools.zip -d /opt/android
# 确认解压后 adb 的真实层级,避免多套一层目录
find /opt/android -maxdepth 2 -name "adb*" -type f
# 赋可执行权限(zip 包在部分系统上会丢掉权限位)
chmod +x /opt/android/platform-tools/adb
chmod +x /opt/android/platform-tools/fastboot
# 验证
/opt/android/platform-tools/adb version
-o 表示覆盖已有文件,升级或重装时不用先删目录;-d 指定解压目标,比先 cd 再解压更不容易把文件撒错地方;find 那一步是关键,-maxdepth 2 只看两层,-type f 只列文件,输出会直接告诉你 adb 到底在第几层,PATH 就照这个结果配。Windows 下可以用 PowerShell 的 Expand-Archive -DestinationPath C:\android,解压完在资源管理器里逐层点进去确认,别只看文件夹名字。
提示:解压完先跑一次绝对路径的
adb version。绝对路径能跑、直接敲adb不能跑,问题一定在 PATH,不在二进制本身。
2.2 路径命名:空格、中文和同步盘都会让报错变得玄学
目录位置定了,还要看目录名字。我坚持路径里不含空格、不含中文、不放在同步盘里,原因不是洁癖。adb 在拉起后台 server 时会把自己的路径写进进程信息,路径里一旦有空格或中文,某些脚本调用、某些 IDE 内置终端在拼接命令时就会截断,报错表现还特别玄学——提示的是“命令找不到”,而不是“路径错误”。你顺着“命令找不到”去查 PATH,查半天都是对的。
同步盘是另一个隐蔽点。同步客户端会在后台占用文件句柄、延迟写入,升级 platform-tools 时替换二进制容易失败,或者出现新旧文件混着用的情况。表现是 adb version 一会儿一个新、一会儿一个旧,看着像灵异事件。把工具目录挪出同步范围,这类问题基本就没了。
反例不用多举:C:\Users\某开发者\我的 工具\platform-tools 这种路径,空格和中文各占一个,出事只是时间问题。改成 C:\android\platform-tools,后面所有脚本、IDE、终端都省心。
2.3 PATH 配置:追加而不是覆盖,顺序决定叫到哪一个
PATH 的目标只有一个:在任意目录下敲 adb,系统都能找到同一份二进制。Linux/macOS 上改 shell 配置文件,bash 用 ~/.bashrc,zsh 用 ~/.zshrc,把工具目录追加到 PATH 末尾或前面。
bash复制# 追加到当前 shell 的 PATH,写进配置文件才会长期生效
export PATH="/opt/android/platform-tools:$PATH"
# 让修改立即生效(按你实际使用的 shell 选择)
source ~/.zshrc
# 验证叫到的是哪一份 adb
which adb
这里有两个细节。第一,用 :$PATH 追加,不要写成 export PATH="/opt/android/platform-tools" 把原值覆盖掉,覆盖之后系统自带命令会一批批失效,现场很难看。第二,把工具目录放在 PATH 前段还是后段,决定多份 adb 共存时先叫到谁;我一般放在前段,让自己指定的这份优先。
Windows 下在“系统属性 → 环境变量”里编辑 Path,新增一条 C:\android\platform-tools,注意是编辑已有的 Path,不是新建一个同名变量把原来的盖掉。改完必须新开一个终端窗口,老窗口读的还是旧环境。
2.4 权限与版本验证:两行输出确认工具真的可用
zip 包在部分系统上会丢掉可执行权限位,解压完直接跑会得到 Permission denied。这不是工具问题,补一次 chmod +x 就好。Windows 一般不涉及这一步,但通过某些同步或传输方式拿到文件后,仍要确认文件没有被标记成不可执行。
验证用 adb version,输出里重点看两样:版本串和二进制路径。路径要跟你配进 PATH 的目录一致,不一致说明系统叫到的是另一份 adb,后面所有“命令行为跟文档对不上”的怪事都能从这里找到根。
bash复制# 同时确认版本与二进制路径
adb version
# 如果输出路径与预期不符,列出 PATH 上所有同名命令
type -a adb
type -a 会把 PATH 上所有叫 adb 的条目按顺序列出来,第一行就是实际生效的那份。这一步在接手别人机器时特别有用,能省掉很多“为什么我的命令跟你的不一样”的争论。
3. adb devices 的三态输出:device、unauthorized、offline 各走哪条路
adb devices 大概是被敲得最多的一条命令,输出只有两列,信息量却不小。序列号后面跟的状态词决定你接下来该动哪里:device 是通了,unauthorized 是设备端还没认这台电脑,offline 是连接建立了但调试通道没起来。三者混在一起处理,就会出现在驱动、数据线、授权弹窗之间来回横跳的情况。
3.1 device:正常握手之后先把定向做对
看到序列号后面是 device,说明 server 起来了、设备认了、调试通道也通了。这时候别急着敲下一条命令,先把“对哪台设备操作”这件事定下来。多台设备同时连着时,不带 -s 的命令会直接报错,提示有多个设备。
bash复制# 列出当前连接的所有设备
adb devices
# 指定序列号,避免多设备歧义
adb -s <serial> shell getprop ro.product.model
# server 状态不对时,先重启 server 再列设备
adb kill-server
adb start-server
adb devices
-s 后面跟的是 adb devices 第一列那串序列号,不是设备型号。kill-server 和 start-server 是一对:前者结束当前后台进程,后者按当前 PATH 上的 adb 重新拉起。很多“设备明明连着却列不出来”的情况,重启一次 server 就能恢复,因为卡住的是后台进程,不是设备。也可以用一个环境变量替代反复写 -s,让当前终端会话默认指向某台设备,脚本里尤其省事。
3.2 unauthorized:授权弹窗没出现,别急着怪线
序列号后面是 unauthorized,意思是设备认到了这台电脑,但调试授权还没确认。正常情况下设备屏幕上会弹一个 RSA 指纹对话框,勾选“始终允许”再确认就好。现实里常见的两种情况:弹窗被忽略或点了拒绝;以及弹窗压根没出现。
弹窗没出现,先做最简单的动作——拔掉数据线重新插一次,同时盯着设备屏幕。还不行,就是本机的 adb 密钥跟设备端记录对不上,需要让 adb 重新生成密钥对。
bash复制# 关闭 server,移除旧的 adb 密钥对,再重新拉起
adb kill-server
rm -f ~/.android/adbkey ~/.android/adbkey.pub
# 重新插线后列设备,设备端应重新弹出授权框
adb devices
Windows 下对应的目录是 %USERPROFILE%\.android,删的文件名相同。adbkey 是私钥,adbkey.pub 是公钥,两个一起删才会重新生成。这里有个代价要提前知道:删掉密钥对之后,之前授权过这台电脑的所有设备都要重新确认一遍。所以这不是日常操作,只在授权链路确实坏了的时候用。
注意:授权对话框里的“始终允许”是设备端的记忆,换线、换 USB 口一般不影响,但删除本机密钥对之后会全部失效。
3.3 offline 与 no permissions:一个查通道,一个查系统权限
offline 的典型表现是序列号在,状态是 offline,任何 adb shell 都卡住或直接失败。原因通常在三处:设备端 adbd 没正常起来、本机 server 状态卡死、USB 连接质量差。处理顺序我固定为:先 adb kill-server 再 adb devices,不行就拔插换口,再不行重启设备端调试开关,最后才怀疑线材。顺序反过来做,容易在换线换口上耗掉一上午,结果只是 server 卡了。
Linux 上还会遇到另一种输出:设备列出来了,状态位置写的是 no permissions。这不是授权问题,是当前用户没有直接访问该 USB 设备的权限。常见做法是加一条 udev 规则,把设备厂商 ID 加进可访问的用户组。
bash复制# 先用 lsusb 查到设备的厂商 ID 与产品 ID
lsusb
# 规则文件示例:idVendor 替换成 lsusb 输出里实际看到的值
# SUBSYSTEM=="usb", ATTR{idVendor}=="<vendor_id>", MODE="0660", GROUP="plugdev"
# 重新加载规则并确认当前用户在该组内
sudo udevadm control --reload-rules
groups
规则里的 idVendor 必须用 lsusb 实际输出替换,不要照抄别人的值。MODE="0660" 给组读写权限,GROUP="plugdev" 指定可访问的用户组,当前用户要在这个组里才生效,改完组需要重新登录。这类问题在换一台机器、换一个桌面环境后最容易复现,跟设备本身没关系。
| 状态 | 含义 | 优先动作 |
|---|---|---|
| device | 握手完成,可执行命令 | 用 -s 指定设备,开始操作 |
| unauthorized | 设备端未确认调试授权 | 重插线看弹窗,必要时重建密钥对 |
| offline | 通道建立但调试未就绪 | 重启 server、换口、重启调试开关 |
| no permissions | 系统层 USB 访问受限 | 查 lsusb,补 udev 规则与用户组 |
4. fastboot 刷写:从握手到分区写入的操作边界
adb 管的是系统起来之后的调试通道,fastboot 管的是 bootloader 阶段的刷写,两者用的不是同一套底层连接。很多人 adb 用得很熟,一进 fastboot 就乱:fastboot devices 列不出设备、分区名凭印象写、刷完不知道有没有生效。这一章把握手、写分区、验证三段拆开说。
4.1 握手:先确认 fastboot devices 看得到序列号
进 bootloader 有两条路:设备关机后按组合键,或者系统正常时用 adb 命令切过去。后者省事,前提是 adb 已经处于 device 状态。
bash复制# 从系统切到 bootloader
adb reboot bootloader
# 确认 fastboot 能看到设备,输出应为序列号加 fastboot
fastboot devices
# 看不到设备时,先确认当前确实在 bootloader 界面
fastboot getvar product
fastboot devices 的输出比 adb devices 更短,正常就是序列号加一个 fastboot 词。列不出来时按三层排查:设备是不是真的进了 bootloader 界面(有的机器只是重启,没进)、USB 连接是不是还通、系统有没有对应的 USB 驱动。第三点在 Windows 上尤其常见,设备管理器里会出现一个带感叹号的未知设备,装好驱动才能被 fastboot 认到。
fastboot getvar product 是握手成功后的第一条确认命令,能返回产品名说明通道完全通了。这条命令本身不改任何东西,适合在动手刷之前跑一次。
4.2 flash:分区名必须来自设备,不能凭印象
fastboot flash 的命令结构很简单:fastboot flash <分区名> <镜像文件>。真正容易出事的是分区名。boot、system、recovery 这些是大家背得出来的,但不同设备的分区表差别很大,双槽位设备还有槽位区分,凭印象写要么报 unknown partition,要么写到不该写的位置。
bash复制# 先列出设备支持的所有变量,分区相关信息以此为准
fastboot getvar all
# 刷写单个分区,分区名与镜像路径都要写全
fastboot flash boot ./boot.img
# 刷完立即重启回系统
fastboot reboot
getvar all 的输出比较长,重点找分区名相关的行,以及当前槽位之类的信息。分区名以这份输出或厂商刷机包里附带的清单为准,不要从别的机型照抄。fastboot flash 后面的镜像路径建议写相对路径或绝对路径的完整形式,不要只写文件名就指望它在当前目录,脚本里尤其容易出这种错。
刷写过程中不要拔线,也不要在同一条命令还没返回时重复敲。fastboot 的写入是分块传输,中途断开轻则分区内容不完整,重则设备停在 bootloader 起不来。真断了,重新进 bootloader 再刷一次同一个分区,通常能恢复。
4.3 验证与回退:刷完先看设备能不能正常回来
刷完一条分区命令,不要立刻连着刷下一条。先 fastboot reboot,等设备重启,再用 adb devices 确认它回到 device 状态。回来了,说明至少启动链路是通的;回不来,停在开机画面或反复重启,问题就锁定在刚刷的那个分区上。
回退这件事要提前想清楚。bootloader 解锁状态、分区写入权限这些边界因设备而异,解锁操作通常会清掉用户数据,这不是可以随手试的动作。我的习惯是:刷之前确认设备当前处于什么状态、要刷的分区有没有备份、刷写命令是不是只指向明确的那一个分区。三条都确认过再动手,比刷坏了再找后悔药强。
还有一点常被忽略:刷写完成后不要马上把工具目录挪走或升级 platform-tools。验证阶段还要反复用 adb 和 fastboot,工具中途换版本,出问题时连“到底是刷坏了还是工具换了”都分不清。
5. 避坑现场:五个能把代码开发工具卡住的细节
前面几章是按正常流程走的,这一章反过来,按现场现象倒推。下面五条都是我在不同机器上真实遇到过的,每条都按“看到什么、为什么、怎么解”写,能对上其中一条,基本就省掉半天的排查。
5.1 解压多套一层,PATH 指到了外层
现象:终端里敲 adb 提示命令找不到,但进到解压目录里能看到 platform-tools 文件夹,双击里面的 adb.exe 也能弹出用法说明。
原因:解压时选了“解压到当前文件夹”,实际落地是 platform-tools/platform-tools/adb.exe,PATH 配的是外层,系统在外层找不到可执行文件。
解决:用 find 或资源管理器确认二进制的真实层级,PATH 指到含 adb 的那一层。升级时用 unzip -o 覆盖到同一目录,避免新旧两层并存。
5.2 路径里有空格或中文,报错指向别处
现象:命令行里敲 adb 能用,一放进脚本或 IDE 内置终端就报“命令找不到”,手动把命令复制出来执行又是好的。
原因:adb 拉起 server 时会把自身路径写进进程信息,路径含空格或中文时,某些调用方拼接命令会截断,报错表现成命令不存在,而不是路径错误。
解决:把工具目录挪到不含空格、不含中文、不同步盘的位置,例如 C:\android\platform-tools 或 /opt/android/platform-tools,改完 PATH 后新开终端验证。
5.3 机器上有多份 adb,server 打架
现象:adb devices 一会儿能列出设备,一会儿列表为空;IDE 里能看到设备,命令行看不到;或者反过来。重启电脑能好一阵,过段时间又复发。
原因:IDE 自带一份 adb、系统目录里还有一份、PATH 上又指了一份,不同版本各自拉起 server,后启动的会把先启动的顶掉,设备列表因此时有时无。
解决:用 type -a adb 列出 PATH 上所有同名命令,只保留一份作为主用,其余从 PATH 移除或在 IDE 设置里指向同一路径。切完执行一次 adb kill-server,让 server 由当前这份 adb 重新拉起。
5.4 线材和 USB 口造成的假故障
现象:设备明明连着,adb devices 空列表,或者状态在 device 和 offline 之间跳;换一台电脑同样的线又是好的。
原因:部分数据线只供电不传数据,前面板 USB 口供电或信号质量不足,转接头、扩展坞也会引入同样的问题。
解决:先用一条确认能传数据的线,直插机箱后面板的口,去掉中间所有转接。换线换口之后再 adb kill-server 重新列设备,不要在看不清状态的时候反复重启设备。
5.5 fastboot 分区名凭印象写
现象:fastboot flash 返回 unknown partition,或者命令成功了但设备重启后功能异常。
原因:分区名跟设备实际分区表对不上,双槽位设备的槽位也没确认,凭经验照抄了别的机型。
解决:动手前先 fastboot getvar all,分区名以输出或厂商刷机包清单为准;一次只刷一个明确的分区,刷完 fastboot reboot 并用 adb devices 确认设备能正常回来,再决定下一步。
6. 进阶习惯:把 adb 和 fastboot 收进脚本时要固定哪几件事
工具用顺之后,下一步多半是写脚本。脚本里最容易出问题的不是命令本身,而是“当前 shell 叫到的是哪份 adb”和“这次操作的是哪台设备”这两件事没固定。我现在的做法是:脚本开头写死工具绝对路径,先重启 server,再从 adb devices 的输出里取处于 device 状态的序列号,后面所有命令都带 -s。
bash复制#!/usr/bin/env bash
# 固定路径,不依赖当前 shell 的 PATH
ADB=/opt/android/platform-tools/adb
FASTBOOT=/opt/android/platform-tools/fastboot
# 确保 server 由这一份 adb 拉起
"$ADB" kill-server
"$ADB" start-server
# 只取第一台处于 device 状态的设备;多设备场景改成显式传序列号
serial=$("$ADB" devices | awk 'NR>1 && $2=="device" {print $1; exit}')
if [ -z "$serial" ]; then
echo "no device in device state"
exit 1
fi
# 后续命令全部带 -s,避免多设备歧义
"$ADB" -s "$serial" install -r app-debug.apk
awk 那行的作用是跳过 adb devices 的第一行表头,只匹配状态列为 device 的行,取第一条序列号就退出。这样写的好处是 unauthorized、offline 的设备会被自动排除,脚本不会把命令发到一台还没准备好的设备上。-r 表示覆盖安装已存在的应用,调试阶段常用。
这套写法我是在一次批量刷机的现场逼出来的:当时三台设备同时连着,脚本没带 -s,命令随机落到其中一台上,刷到第二台时才发现装错了机器。从那以后,我每次写这类脚本都强制先固定工具路径、再固定设备序列号,两步都打印出来确认过才往下走。希望帮到你。
