刚接触 Android 开发的人搜“Android SDK下载”最容易掉进两个坑一是跑到第三方站点下载一个来路不明的整包装完发现连 adb 都没有二是下载了 Android Studio却不知道 SDK 还需要单独安装项目一编译就报SDK location not found。事实上Android SDK 并不是一个可以直接下载的大包裹而是一套按功能拆分的工具集合你缺哪部分决定了你该用哪种下载姿势。这篇文章按我给团队新成员做环境的标准流程从选择安装包、配置环境变量到报错排查把 Android SDK 下载这件事一次说清楚。1. 下载之前先分清你要的是完整 Studio还是裸 SDK很多教程把“下载 Android SDK”描述成一件很简单的事好像找到一个压缩包解压就完事。但真正动手时你会发现官方页面提供的是 Android Studio 安装包而不是一个叫android-sdk.zip的东西。这不是官方故意绕弯子而是因为不同角色对 SDK 的需求完全不同。1.1 使用场景决定下载方式四类人的不同选择我建议先把“为什么需要 SDK”想清楚再决定下载哪个入口。下面这张表是我这些年给人排环境时总结出来的选择逻辑使用场景推荐下载方式理由刚入门的 Android 新手完整 Android Studio图形化 SDK Manager下载、升级、删除组件都直观已有 IntelliJ IDEA / 其他 IDESDK 单独安装 IDE 指定目录避免 Studio 自带的配置干扰现有工程CI 构建机、自动化脚本Command-Line Tools可以无界面用 sdkmanager 完成安装只想用 adb / fastboot 调试设备Platform-Tools 单包不需要整套编译环境体积最小这里最容易被忽略的是第四类人。很多做自动化测试、或者搞设备调试的同事其实只需要adb这一个命令但看到网上标题写“Android SDK 下载”就顺手把整个 Android Studio 装了一遍。其实官方早就单独提供了 platform-tools 的下载里面就包含adb.exeWindows或adbmacOS/Linux装完把路径加到PATH里即可。如果你是 Flutter 开发者用的不是 Android Studio 而是 VS Code那么完整 Studio 也不是必需项。我更建议用 Command-Line Tools 下载 SDK再把ANDROID_HOME指向这个目录Flutter 和 Gradle 一样能正常识别。1.2 SDK Manager 里的组件关系Platform、Build-Tools、Platform-Tools 的分工“Android SDK”是个总称真正打开 SDK Manager 后你会发现里面是一堆并列的组件。很多新人的“下载成功但项目跑不起来”本质上是漏装了其中某一项。Platforms;android-XX对应 Android 系统的某个 API 版本比如android-34就是 Android 14。这是编译时能调用哪些系统 API 的基础通常一个项目只会用到其中一个。Build-Tools负责把资源打包、编译成 dex、生成 APK/AAB 的构建工具有独立的版本号比如34.0.0。它和 Platform 是两码事经常出现“platform 装了但 build-tools 没装”的错。Platform-Tools包含adb、fastboot等调试工具不参与编译但连接真机、刷机、抓日志都靠它。Cmdline-Tools就是sdkmanager、avdmanager这些命令行程序自动化安装时靠它操作 SDK Manager。NDK / CMake写 C/C 代码时才需要纯 Java/Kotlin 项目不用管。System Images模拟器运行时使用的系统镜像不做模拟器开发可以不装。用个生活化比喻SDK Manager 就像五金店货架Platform 是一套套尺寸不同的“零件规格”Build-Tools 是拧螺丝的“电动工具”Platform-Tools 是测量用的“卷尺”。你只拧一种螺丝不代表要把整个货架搬回家。1.3 版本号为什么看着这么乱API Level、系统名和目录名Android 的版本号体系是新手最容易懵的地方。手机上看到的是“Android 14”SDK Manager 里写着API 34Gradle 配置文件里写compileSdk 34目录名又是platforms/android-34。这几个名字指的都是同一件事只是不同工具叫法不同。系统版本API LevelSDK Manager 里的名字常见 compileSdkAndroid 1231android-3131Android 1333android-3333Android 1434android-3434Android 1535android-3535我平时处理版本问题时会先问对方一句“你 AndroidManifest 或 build.gradle 里写的 compileSdk 是多少”而不是问“你手机是不是 Android 14”。因为在 SDK 的世界里API Level 才是唯一准确的标识营销名和系统名都可能造成歧义。下载时如果看到一个写着Android 14 (API 34)的条目优先记34。2. 官方渠道下载从 Android Studio 到 sdkmanager搞清楚需要什么之后再来看具体的下载入口。我强烈建议大家只在开发者官网操作不要在搜索引擎里点那些“高速下载”链接。官方页面其实提供了两套完全不同的下载方式对应不同需求。2.1 Android Studio 内安装 SDK 的推荐流程如果你决定用 Android Studio那么不要在线上去找什么“SDK 分离安装包”直接在官网下载对应操作系统的安装包。第一次启动时Studio 会让你选择是否需要导入配置这里选择不导入即可。接着会进入 SDK 组件选择页面如果你不清楚项目需求建议用默认的 SDK Platforms再走下一步让它自动下载。下载完成后有几个地方值得看一眼SDK Location安装时记录下 SDK 的真实路径macOS 上通常是~/Library/Android/sdkWindows 上通常是C:\Users\用户名\AppData\Local\Android\Sdk。SDK Platforms 标签页默认只装当前最新平台如果你的项目compileSdk是 35但本机只有 34编译时会报错。SDK Tools 标签页这里能看到Android SDK Platform-Tools、Android SDK Command-line Tools等选项。建议把 Command-line Tools 也勾上后面写脚本、查版本都会用到。很多人以为装好 Android Studio 就等于有了 SDK其实 Studio 只是 IDESDK 组件是它帮你下载到本地目录里的。两者一旦分离比如你把项目拿到另一台只装了 IDEA 的电脑上马上就会遇到环境变量问题。2.2 cmdline-tools 的正确目录结构不用 Android Studio 的人通常会去官网的 Command-Line Tools 页面下载一个 zip 包。这个包非常容易出问题原因在于它的目录结构很“挑剔”。官方 zip 解压后第一层目录叫cmdline-tools里面又有bin、lib等子目录。如果你图省事把解压出来的cmdline-tools直接放到 SDK 根目录运行sdkmanager时大概率会报SDK location not found或者Filesystem root is not valid。正确做法是把它放到cmdline-tools/latest这个层级下也就是你的SDK根目录/ ├── cmdline-tools/ │ └── latest/ │ ├── bin/ │ │ ├── sdkmanager │ │ └── avdmanager │ └── lib/ ├── platform-tools/ ├── platforms/ │ └── android-34/ └── build-tools/ └── 34.0.0/我重点说一下为什么是latest。sdkmanager 在初始化时会假设cmdline-tools下面有一个固定的 “最新版本目录” 来感知 SDK 根路径。没有这层嵌套它就无法判断哪些目录是 SDK 组件哪些是你自己建的普通文件夹。这个坑在 CI 镜像里尤其常见很多 Dockerfile 就是卡在这一步。2.3 用 sdkmanager 安装 Platform 和 Platform-Tools 的命令目录结构摆好以后安装组件就很直接了。先打开终端进入cmdline-tools/latest/bin或者把这个目录加入PATH然后执行# 查看仓库里所有可用组件 sdkmanager --list # 安装 platform-tools 和 Android 14 的 Platform sdkmanager platform-tools platforms;android-34 # 安装指定版本的 build-tools sdkmanager build-tools;34.0.0命令里的分号是固定的命名格式不要省略否则 SDK Manager 识别不到对应组件。我习惯在一条命令里把所有需要的东西写完比如sdkmanager platform-tools platforms;android-34 platforms;android-35 build-tools;34.0.0这样能减少重复搜索的时间。如果你是在 CI 脚本里执行建议把--sdk_root参数也加上明确指定 SDK 根目录避免环境变量不一致导致装到奇怪的位置sdkmanager --sdk_root$ANDROID_HOME platform-tools platforms;android-342.4 如何确认下载的文件是官方原版“官方正品”这件事不是随便说说的。Android SDK 里包含编译工具和调试工具第三方修改过的包轻则功能异常重则连日志都被劫持。我见过有人从网盘下载所谓“绿色版 SDK”解压后adb命令能用但连接设备时协议版本对不上折腾了一下午最后还是换回官方包。验证方式其实很简单官网每个 zip 包旁边都会提供 SHA-256 校验值下载完先做一次校验再解压。# macOS / Linux shasum -a 256 commandlinetools-mac-11076708_latest.zip # Windows PowerShell Get-FileHash .\commandlinetools-win-11076708_latest.zip -Algorithm SHA256对比校验值一致后再使用。如果官网偶尔下载超时可以换个非高峰时段重试但不要因此去找来源不明的加速镜像。安全这块不值得赌。3. 环境变量配置ANDROID_HOME、PATH 和验证命令下载和安装只是第一步真正让工具链认得出 SDK靠的是环境变量。这块配置错了命令行 Gradle、Flutter、adb 都可能找不到 SDK。我把最常见的排查链路整理出来照着走能省不少时间。3.1 两个环境变量为什么建议一起配环境中常见的变量有两个ANDROID_HOME和ANDROID_SDK_ROOT。它们的作用几乎一样都是告诉工具“Android SDK 装在哪个目录”。老一些的工具读ANDROID_SDK_ROOT新一些的读ANDROID_HOME为了兼容我建议两个都配成同一个值成本只有一行。macOS 或 Linux 下在~/.zshrc或~/.bashrc里加export ANDROID_HOME$HOME/Library/Android/sdk export ANDROID_SDK_ROOT$ANDROID_HOMEWindows 下建议通过“系统属性 - 环境变量”新建变量名: ANDROID_HOME 变量值: C:\Users\你的用户名\AppData\Local\Android\Sdk 变量名: ANDROID_SDK_ROOT 变量值: C:\Users\你的用户名\AppData\Local\Android\Sdk为什么不直接用命令行setx来写因为setx修改环境变量后新开的终端才会生效而且如果拼接PATH的写法不对很容易把原有路径截断。图形界面虽然点起来慢点但稳定得多。3.2 PATH 添加哪两个目录才够用环境变量告诉工具 SDK 在哪PATH则是让我们能在终端里直接敲adb、sdkmanager。大多数人只需要把这两个目录加进去$ANDROID_HOME/platform-tools提供adb、fastboot$ANDROID_HOME/cmdline-tools/latest/bin提供sdkmanager、avdmanagermacOS / Linuxexport PATH$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/binWindows 则在环境变量编辑界面里分别新建两条%ANDROID_HOME%\platform-tools %ANDROID_HOME%\cmdline-tools\latest\bin这里很多人会踩一个来自老教程的坑把$ANDROID_HOME/tools也加进PATH。这个目录在旧版 SDK 里确实有android命令但从 Android 26 以后已经被废弃新安装的 SDK 根本不会有这个目录。如果你的PATH里还留着它不影响使用但也别再专门去下载老版本 tools。3.3 配置完如何验证三条命令定位 90% 的问题配置完环境变量我习惯立刻跑三条命令而不是直接打开一个大型项目去试否则报错时很难分辨是 SDK 问题还是项目问题。# 1. 确认环境变量 echo $ANDROID_HOME # 2. 确认 adb adb --version # 3. 确认 sdkmanager sdkmanager --list_installed在 Windows 的 cmd 里第一条改成echo %ANDROID_HOME%。如果echo有输出但adb --version提示找不到命令说明PATH没加上或者新终端没重开。如果adb能用但sdkmanager --list_installed报错十有八九是第 2.2 节说的目录结构问题检查一下是不是少了latest这一层。另一个容易忽略的点是终端修改完.zshrc后记得执行source ~/.zshrc或重开终端而不是继续在旧终端里敲命令。4. 从报错反推 SDK 问题四个高频场景的排查链路SDK 下载装好之后真正让人难受的是项目跑到一半突然报错。我在日常工作里遇到过大量类似问题发现它们其实都有固定套路。下面按出错概率从高到低列一下。4.1 SDK location not found先查 local.properties再查环境变量这是新建项目、或者把项目从别人电脑拷过来后最常见的错误。Gradle 找 SDK 的顺序大致是先看项目根目录的local.properties里有没有sdk.dir再看环境变量ANDROID_HOME都没有就会报SDK location not found。local.properties这个文件是跟着项目走的但通常不会被提交到 Git。如果你拿到一个项目运行报这个错第一反应不是重装 SDK而是打开项目根目录创建或修改local.propertiessdk.dir/Users/你的用户名/Library/Android/sdkWindows 上路径里的反斜杠要注意转义我更喜欢直接用正斜杠Java properties 文件是支持的sdk.dirC:/Users/你的用户名/AppData/Local/Android/Sdk改完保存后重启 Gradle 同步问题基本就解决了。4.2 Failed to find target with hash string android-XX缺的是平台包这个报错属于“字面意思最明确、解决最直接”的一种。比如你在build.gradle里写了compileSdk 35但本机 SDK Manager 只安装了android-34Gradle 就会说找不到目标平台。处理方式就是在 SDK Manager 里找到对应 API Level 勾选安装或者用命令行sdkmanager platforms;android-35这里我多提醒一句不要为了省事把compileSdk改成 34除非项目根本没有用 35 的新 API。如果改了compileSdk却不改依赖库的最低要求后续可能冒出AAPT2 error或资源定位问题反而更难处理。该装的平台还是装一下比较稳妥。4.3 Build Tools revision 缺失别急着升 AGP 版本另一个高频报错是这样的Failed to find Build Tools revision 30.0.2这个和 Platform 缺失不一样它指的是编译打包时用的build-tools版本不够。每个 Android Gradle PluginAGP版本都有一个默认的 Build Tools 版本比如 AGP 8.x 通常会配34.0.0。最简单的做法是补装对应的 Build Toolssdkmanager build-tools;30.0.2或者让 AGP 自己决定默认版本。如果你在build.gradle里强行写了buildToolsVersion建议先删掉用插件默认配置。非要手动指定时必须确保本机确实装了那个版本否则就是给自己挖坑。4.4 license 没接受所有“装完不能用”里最好解决的一种命令行安装时很多人会看到组件下载 100% 了但最后提示License for package Android SDK Platform 34 not accepted然后整个安装过程被判定失败。这是因为 sdkmanager 不会默认接受协议需要你手动确认。手动接受一次也可以但组件多了容易漏。我的做法是无条件接受yes | sdkmanager --licensesWindows 命令行里yes命令不存在可以用 PowerShellfor ($i0; $i -lt 30; $i) { y | sdkmanager --licenses }或者在交互式终端里连续敲几次y。接受完之后重新安装刚才失败的组件就能正常写入 SDK 目录了。5. 多项目、换机器SDK 管理的三个实操建议最后聊一点长期维护的心得。Android SDK 不是装一次就一劳永逸项目多了之后版本管理、目录规划、迁移备份都需要提前想清楚。5.1 一台机器一份 SDK 根目录里面可以放多个 Platform我见过有人电脑上装了三四份 Android SDK分别放在不同磁盘理由是“不同项目要用不同版本”。其实这完全没必要SDK Manager 本来就支持在同一个根目录下安装多套 Platform 和 Build-ToolsGradle 构建时会自动查找对应版本。更好的做法是保持一个根目录比如 macOS 的~/Library/Android/sdk在这个目录下并排存在platforms/android-34、platforms/android-35。磁盘空间允许的话直接装最近的 2 到 3 个 API Level基本能覆盖绝大多数项目也不用频繁换版本。如果某些老项目的构建工具特别旧尽量通过 AGP 版本升级来平滑过渡而不是长期维护一个 2015 年的 SDK 目录。老版本工具链兼容性差新机系统一升级问题比收益多。5.2 local.properties、ANDROID_HOME、Global SDK 的优先级项目构建时local.properties里的sdk.dir优先级要高于环境变量ANDROID_HOME。所以在命令行里明明echo $ANDROID_HOME有输出项目却报 SDK 找不到时先查项目根目录有没有一个“指向错误路径”的local.properties。另外要注意local.properties是用户本机配置不应该提交到 Git。把sdk.dir写死到代码仓库里等于给每个同事都埋了一颗雷路径稍微不同就全部编译失败。正确姿势是在团队文档里写清楚 SDK 安装路径让大家第一次拉代码时自己配置。如果你是 Android Studio 用户其实也可以不手动写local.properties在File - Project Structure - SDK Location里指定一次Studio 会自动生成或更新这个文件。5.3 迁移 SDK 时除了复制目录还要带上 licenses换电脑或迁移 CI 机器时有人会直接把整个 SDK 目录压缩拷到新机器结果发现组件都在但一构建就卡在 license 提示上而且不是每次都提示很诡异。原因多半是拷贝的时候只复制了platforms、build-tools这些显眼目录漏掉了 SDK 根目录底下的licenses文件夹。这个文件夹里存放着你已经接受过的协议记录比如android-sdk-license。没有它sdkmanager 会认为所有组件都是未经授权的可能在构建中直接中止。迁移后检查一下ls $ANDROID_HOME/licenses如果确实没有重新执行一次yes | sdkmanager --licenses比起手动复制 licenses我现在的习惯是迁移机器时只备份platform-tools、build-tools、platforms以及cmdline-tools其他组件让 sdkmanager 按需重新安装。系统镜像这类体积大、又容易因为版本差异产生兼容问题的东西也不建议跨机器拷贝让它在新机器上重新下载反而更省心。我的经验是Android SDK 下载这件事从来不是“下载完就好了”而是“下载完之后能不能让工具链稳定认出你下载的东西”。环境变量、目录结构、license 这三样任何一个出问题都会让你怀疑是不是安装包坏了。把这套流程理顺之后无论换机器还是升级版本都能做到心中有数。