ADB 这个东西做 Android 开发、搞自动化测试、折腾电视盒子和模拟器的朋友都不陌生。但每次换新 Mac或者帮同事配环境最常听到的一句话就是我 brew install 一下不就行了。Homebrew 确实省事可现实里你会遇到一堆它搞不定的场景公司内网机器装不了 Homebrew、Intel 老 Mac 上 Homebrew 报错装不动、需要指定某个版本的 platform-tools、CI 流水线里不想引入 Homebrew 依赖、或者你只是想临时用一下 ADB 抓个日志。这些情况下手动安装加手动配置环境变量才是真正靠谱的路子。这篇内容就是把我这些年在一堆 Mac 上装 ADB 的经验摊开讲。核心围绕三件事除了 Homebrew 之外还有哪几种安装方式、每种方式适合什么场景、以及手动配置环境变量时那些让人抓狂的坑怎么绕过去。不管你是刚接触 ADB 的新手还是被command not found: adb折磨过的老手都能从里面找到能直接抄的步骤。我会把每一步为什么这么做讲清楚而不是甩几条命令让你自己猜。1. 先搞清楚 ADB 到底装的是什么1.1 ADB 不是单独一个可执行文件很多人以为 ADB 就是一个adb二进制下载下来丢进 PATH 就完事。实际上你从官方拿到的是一整个platform-tools目录里面除了adb还有fastboot、etc1tool、dmtracedump、hprof-conv、make_f2fs、sqlite3等一堆工具。adb本身在运行时会依赖同目录下的一些库和辅助程序尤其是fastboot和adb经常要配合使用。这就解释了一个常见现象有人只把adb这一个文件复制到/usr/local/bin结果adb devices能用但fastboot找不到或者某些命令报奇怪的错。所以正确的做法永远是整个platform-tools目录一起放然后把目录路径加进 PATH而不是单独拎一个文件出来。1.2 为什么版本这件事比你想的重要ADB 的版本和 Android 系统版本、以及你用的设备是有兼容关系的。老版本 ADB 连新系统设备可能出现adb server version doesnt match或者直接unauthorized新版本 ADB 连一些老设备比如老款创维电视、老盒子有时反而握手失败。热词里出现的adb unauthorized怎么解决、vivo adb精简列表、老款创维如何打开adb本质上很多都是版本和授权机制的问题。官方platform-tools是持续更新的但更新频率不高一般几个月一次。我的建议是日常开发用官方最新稳定版遇到特定老设备连不上时再回头换一个稍旧的版本试。这也是为什么我不推荐完全依赖 Homebrew——Homebrew 的android-platform-tools版本更新有延迟而且你没法方便地在多个版本之间切换。1.3 三种安装路径的适用场景对照在动手之前先对号入座选对方式能省掉后面一堆麻烦。安装方式适合场景优点缺点Homebrew个人 Mac、网络通畅、追求省事一条命令搞定升级方便内网装不了、版本滞后、Intel Mac 可能报错官方压缩包手动安装公司内网、需要指定版本、CI 环境版本可控、无外部依赖、可多版本共存需要手动配 PATHSDK Manager 安装已装 Android Studio 的开发者和 SDK 统一管理、自动更新依赖 Android Studio 生态、体积大下面几节我会把后两种也就是 Homebrew 之外的展开讲透因为这才是这篇的重点。2. 官方压缩包手动安装最通用也最可控的方式2.1 下载与解压的正确姿势官方platform-tools的下载入口在 Android 开发者官网的 SDK 页面直接搜 platform-tools download 就能找到。注意选择 macOS 版本下载下来是一个 zip 包名字类似platform-tools-latest-darwin.zip。解压之后你会得到一个platform-tools文件夹。这里第一个坑就来了别把它放在下载文件夹里直接用。原因有两个一是下载文件夹容易被清理软件误删热词里mac系统数据怎么清理、mac卸载软件都是高频操作二是路径里如果带中文或空格后面配 PATH 时容易出问题。我习惯放在一个固定的、路径干净的位置比如mkdir -p ~/Library/Android mv ~/Downloads/platform-tools ~/Library/Android/放好之后确认一下目录内容ls ~/Library/Android/platform-tools你应该能看到adb、fastboot、sqlite3等文件。如果只看到一个adb说明你下载的不是完整包重新下。2.2 首次运行会被 Gatekeeper 拦下来这是 macOS 上手动装 ADB 最经典的坑没有之一。你第一次在终端里执行./adb version很可能看到这样的提示zsh: permission denied: ./adb或者弹出一个系统对话框说无法打开因为无法验证开发者。这不是文件坏了是 macOS 的安全机制Gatekeeper在拦。因为从网上下载的二进制默认没有可执行权限而且会被打上隔离属性quarantine。解决分两步。先加可执行权限chmod x ~/Library/Android/platform-tools/adb chmod x ~/Library/Android/platform-tools/fastboot如果还是被拦去掉隔离属性xattr -d com.apple.quarantine ~/Library/Android/platform-tools/adb提示xattr这条命令只对当前文件生效如果整个目录里的工具都要用可以加-r递归处理整个目录。但要注意去掉隔离属性意味着你信任这个来源官方下载的包可以放心操作。我踩过的一个坑是只给adb加了权限结果跑fastboot时又报一次 permission denied白白多折腾十分钟。所以整个目录里的可执行文件最好一次性都处理掉。2.3 验证安装是否真的成功加完权限后用绝对路径跑一下~/Library/Android/platform-tools/adb version正常会输出类似Android Debug Bridge version 1.0.41 Version 34.0.5-android-tools看到版本号就说明二进制本身没问题了。这一步很关键因为如果这里就报错那后面配 PATH 也是白配。先用绝对路径验证再配环境变量这个顺序能帮你快速定位问题到底出在文件本身还是 PATH 配置上。3. 环境变量配置手动安装真正的分水岭3.1 为什么配了 PATH 还是 command not found这是被问得最多的问题。你在~/.zshrc里加了export PATH$PATH:~/Library/Android/platform-tools然后source ~/.zshrc结果新开一个终端窗口adb还是找不到。原因通常有这几个第一改错了配置文件。macOS 从 Catalina 开始默认 shell 是 zsh配置文件是~/.zshrc。但如果你用的是 bash那要改~/.bash_profile或~/.bashrc。热词里环境变量配置、java环境变量配置失败、ubuntu环境变量配置错误这些问题一大半都是改错了文件。第二用了~但没被正确展开。在某些配置场景下PATH 里的~不会被展开成家目录。稳妥的做法是写绝对路径或者用$HOMEexport PATH$HOME/Library/Android/platform-tools:$PATH第三PATH 拼接顺序写反了。如果你写成export PATH$PATH:$HOME/...把新路径加在末尾那么当系统里已经有一个旧版 adb比如之前 Homebrew 装的时会优先用旧的那个。想让自己指定的版本优先就要把新路径放在前面。3.2 zsh 和 bash 的配置差异要分清先确认你当前用的是哪个 shellecho $SHELL输出/bin/zsh就是 zsh输出/bin/bash就是 bash。然后对应修改zsh编辑~/.zshrcbash编辑~/.bash_profile登录 shell或~/.bashrc交互式非登录 shell用你顺手的编辑器打开比如open -e ~/.zshrc在文件末尾加上这一行export PATH$HOME/Library/Android/platform-tools:$PATH保存后让配置立即生效source ~/.zshrc注意source只对当前这个终端窗口生效。要验证是否真的持久化必须新开一个终端窗口再敲adb version。很多人 source 完能用就以为搞定了结果重启电脑又不行就是因为没做这一步验证。3.3 验证 PATH 是否真的生效配完之后用这几条命令逐层排查which adb echo $PATH | tr : \n | grep platform-tools adb versionwhich adb应该输出你配置的那个路径。如果输出的是/usr/local/bin/adb或/opt/homebrew/bin/adb说明系统里还有另一个 adb 在抢位置需要处理冲突见下一节。echo $PATH那条能把 PATH 按行拆开方便你确认路径确实加进去了。4. 多版本共存与冲突处理4.1 Homebrew 版和手动版打架怎么办如果你之前用 Homebrew 装过android-platform-tools现在又手动装了一份两个 adb 就会打架。表现是你明明配了手动版的 PATHwhich adb却指向 Homebrew 的路径。这是因为 Homebrew 的路径Intel Mac 是/usr/local/binApple Silicon 是/opt/homebrew/bin通常在 PATH 里排得比较靠前。处理方式有两种。一种是干脆卸载 Homebrew 版brew uninstall android-platform-tools另一种是保留两个版本但通过 PATH 顺序控制默认用哪个。把手动版路径放在 Homebrew 路径之前即可。如果你需要频繁切换可以定义别名alias adb-old$HOME/Library/Android/platform-tools-old/adb这样就能在需要连老设备时手动调用旧版本。4.2 Intel Mac 和 Apple Silicon 的路径差异这一点特别容易被忽略。Apple SiliconM 系列芯片的 MacHomebrew 默认装在/opt/homebrew而 Intel Mac 装在/usr/local。所以网上抄来的 PATH 配置在另一种芯片的机器上可能完全不适用。热词里intel mac 安装不了homebrew了这类问题很多时候就是路径和架构没对上。手动安装的好处在这里就体现出来了你自己决定放哪路径完全可控不受芯片架构和 Homebrew 安装位置的影响。我一般统一放在~/Library/Android/platform-tools这样不管换什么机器配置都一样。4.3 用 alias 做版本切换的实战写法假设你同时保留了新版和旧版两个目录export PATH$HOME/Library/Android/platform-tools:$PATH alias adb-legacy$HOME/Library/Android/platform-tools-legacy/adb日常用adb走新版遇到老设备连不上时用adb-legacy devices试。这种写法在调试老款电视盒子、老款创维设备时特别有用因为那些设备的 ADB 协议实现往往比较旧。5. 那些让人抓狂的实战坑5.1 adb devices 显示 unauthorized 的排查链路这个问题的完整排查顺序是这样的别跳步先看设备端有没有弹出允许 USB 调试的授权对话框。很多人插上设备就开始敲命令根本没注意手机上有个弹窗。如果弹窗出现过但你点了拒绝需要去开发者选项里撤销 USB 调试授权然后重新插拔。检查~/.android/adbkey和~/.android/adbkey.pub是否存在。这两个是 ADB 的密钥对授权就是基于它们的。如果密钥损坏或权限不对会一直 unauthorized。删掉旧密钥重新生成rm ~/.android/adbkey ~/.android/adbkey.pub adb kill-server adb start-server重新插拔设备会重新弹授权框。如果还不行检查是不是有多个 adb server 在跑。ps aux | grep adb看一下有多个就全杀掉再重启。我遇到过一次特别诡异的密钥文件权限被改成了 777导致 ADB 拒绝使用它。改成 600 就好了chmod 600 ~/.android/adbkey5.2 端口被占用导致 server 起不来ADB server 默认监听 5037 端口。如果这个端口被别的程序占了adb start-server会失败报cannot bind to 127.0.0.1:5037。查一下谁占着lsof -i :5037找到 PID 后处理掉或者直接adb kill-server再重启。有些安全软件、模拟器自带的 adb 会偷偷占用这个端口热词里使用夜神模拟器 adb模式就经常遇到模拟器自带 adb 和系统 adb 冲突的情况。解决办法是让模拟器使用系统已有的 adb而不是它自带的那个。5.3 抓日志时环境变量没配好的连锁反应adb logcat是最高频的用法之一。但如果 PATH 没配好你在项目脚本里写的adb logcat就会失败而脚本往往不会给你清晰的报错只显示command not found。更隐蔽的是有些 IDE 或构建工具会调用 adb如果它们启动时的环境变量里没有你的 PATH就会用错版本或者找不到。所以配完 PATH 后记得重启你的 IDE 和终端让它们重新加载环境变量。这一点在adb logcat 抓取日志、adb调试这类场景里特别重要。6. 让 ADB 用起来更顺手的几个配置6.1 把常用命令做成 aliasADB 命令又长又常用做成 alias 能省不少事alias adevadb devices alias alogadb logcat alias arestartadb kill-server adb start-server放在~/.zshrc里和 PATH 配置放一起一次配好长期受益。6.2 无线调试的配置要点现在很多设备支持无线调试。基本流程是先用 USB 连上然后adb tcpip 5555 adb connect 设备IP:5555拔掉 USB 后就能无线用了。注意设备 IP 要确保和 Mac 在同一网段而且有些路由器会隔离设备导致连不上。热词里mac地址怎么查这类需求在排查网络连通性时也会用到。6.3 定期更新 platform-tools 的习惯手动安装的缺点是更新要自己来。我的习惯是每隔一两个月去官网看一眼有没有新版本有就下载替换整个目录。替换前先adb kill-server替换后重新验证版本。这样既保持了版本可控又不会长期停留在老版本上。7. 关于 Homebrew 报错的一些补充虽然这篇重点不在 Homebrew但热词里mac安装homebrew报错、intel mac 安装不了homebrew了出现频率很高简单说两句。Homebrew 装不上常见原因是网络问题国内访问 GitHub 慢、Xcode Command Line Tools 没装、或者 shell 配置里 PATH 没加对。装 Homebrew 前先确保xcode-select --install这个装好了很多编译类的问题就没了。但即便 Homebrew 能用我依然建议你掌握手动安装 ADB 的方法因为它在内网、CI、多版本这些场景下是 Homebrew 替代不了的。8. 我个人的一点经验折腾了这么多台 Mac我现在的固定做法是手动安装 platform-tools 到~/Library/AndroidPATH 写进~/.zshrc同时保留一个旧版本目录备用。Homebrew 只用来装那些我确实需要它管理的工具ADB 这种需要精确控制版本和路径的我宁愿自己管。最后分享一个小技巧把整个~/Library/Android目录打包备份换新电脑时直接解压PATH 配置复制过去五分钟就能恢复完整的 ADB 环境比重新下载配置快得多。这个习惯帮我省下了无数次重复劳动。