企业官网建设流程全解析

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 doesn't match或者直接unauthorized；新版本 ADB 连一些老设备（比如老款创维电视、老盒子）有时反而握手失败。热词里出现的adb unauthorized怎么解决、vivo adb精简列表、老款创维如何打开adb，本质上很多都是版本和授权机制的问题。

官方platform-tools是持续更新的，但更新频率不高，一般几个月一次。我的建议是：日常开发用官方最新稳定版，遇到特定老设备连不上时，再回头换一个稍旧的版本试。这也是为什么我不推荐完全依赖 Homebrew——Homebrew 的android-platform-tools版本更新有延迟，而且你没法方便地在多个版本之间切换。

1.3 三种安装路径的适用场景对照

在动手之前，先对号入座，选对方式能省掉后面一堆麻烦。

下面几节我会把后两种（也就是 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 里的~不会被展开成家目录。稳妥的做法是写绝对路径，或者用$HOME：

export PATH="$HOME/Library/Android/platform-tools:$PATH"

第三，PATH 拼接顺序写反了。如果你写成export PATH=$PATH:$HOME/...，把新路径加在末尾，那么当系统里已经有一个旧版 adb（比如之前 Homebrew 装的）时，会优先用旧的那个。想让自己指定的版本优先，就要把新路径放在前面。

3.2 zsh 和 bash 的配置差异要分清

先确认你当前用的是哪个 shell：

echo $SHELL

输出/bin/zsh就是 zsh，输出/bin/bash就是 bash。然后对应修改：

• zsh：编辑~/.zshrc
• bash：编辑~/.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 version

which adb应该输出你配置的那个路径。如果输出的是/usr/local/bin/adb或/opt/homebrew/bin/adb，说明系统里还有另一个 adb 在抢位置，需要处理冲突（见下一节）。echo $PATH那条能把 PATH 按行拆开，方便你确认路径确实加进去了。

4. 多版本共存与冲突处理

4.1 Homebrew 版和手动版打架怎么办

如果你之前用 Homebrew 装过android-platform-tools，现在又手动装了一份，两个 adb 就会打架。表现是：你明明配了手动版的 PATH，which adb却指向 Homebrew 的路径。这是因为 Homebrew 的路径（Intel Mac 是/usr/local/bin，Apple 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 Silicon（M 系列芯片）的 Mac，Homebrew 默认装在/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 的排查链路

这个问题的完整排查顺序是这样的，别跳步：

1. 先看设备端有没有弹出"允许 USB 调试"的授权对话框。很多人插上设备就开始敲命令，根本没注意手机上有个弹窗。
2. 如果弹窗出现过但你点了拒绝，需要去开发者选项里"撤销 USB 调试授权"，然后重新插拔。
3. 检查~/.android/adbkey和~/.android/adbkey.pub是否存在。这两个是 ADB 的密钥对，授权就是基于它们的。如果密钥损坏或权限不对，会一直 unauthorized。
4. 删掉旧密钥重新生成：

rm ~/.android/adbkey ~/.android/adbkey.pub adb kill-server adb start-server

重新插拔设备，会重新弹授权框。

5. 如果还不行，检查是不是有多个 adb server 在跑。ps aux | grep adb看一下，有多个就全杀掉再重启。

我遇到过一次特别诡异的：密钥文件权限被改成了 777，导致 ADB 拒绝使用它。改成 600 就好了：

chmod 600 ~/.android/adbkey

5.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 把常用命令做成 alias

ADB 命令又长又常用，做成 alias 能省不少事：

alias adev="adb devices" alias alog="adb logcat" alias arestart="adb 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/Android，PATH 写进~/.zshrc，同时保留一个旧版本目录备用。Homebrew 只用来装那些我确实需要它管理的工具，ADB 这种需要精确控制版本和路径的，我宁愿自己管。

最后分享一个小技巧：把整个~/Library/Android目录打包备份，换新电脑时直接解压，PATH 配置复制过去，五分钟就能恢复完整的 ADB 环境，比重新下载配置快得多。这个习惯帮我省下了无数次重复劳动。