做Android开发这一行不管你是写原生、跨平台还是只负责打包几乎都绕不过“Android SDK下载及安装”这道坎。很多人第一次接触以为装了Android Studio就万事大吉结果新建项目时要么卡在SDK路径要么编译时报各种找不到platform的错。这篇文章就把整个过程从头拆一遍SDK是什么、从哪里下载、怎么装、装完怎么配环境变量、各种报错怎么治。这里不会讲太多高深理论只讲实操和踩坑后得出的结论适合刚入坑Android的开发者也适合原来只用IDE、现在想折腾命令行的朋友。另外如果你在用 Flutter、React Native 这类跨平台框架SDK 配置更是基础中的基础因为很多构建报错表面上来自框架实际上就是 SDK 没装对。所以这篇文章也可以当半个排障手册看卡住的时候翻一翻比直接百度要高效。1. Android SDK到底是什么动手之前先搞清楚在下载之前先别急着点“Download”否则很容易装了一堆用不上的东西还占了几个G硬盘。Android SDK不是一个大一统的安装包而是一个按功能拆分的组件集合。下面这些概念如果你不搞懂后面报错你会一脸懵。1.1 SDK目录里的那些文件夹分别都有什么用Android SDK安装完成后你会得到一个根目录里面有多个子文件夹每个文件夹各司其职。最常见的有platforms/存放不同Android版本的平台库目录名一般是android-33、android-34、android-35对应API级别编译项目时compileSdkVersion必须对应这里某个已安装的平台版本。build-tools/是编译工具链包含 AAPT2、D8/R8、zipalign 等负责把资源和字节码打包成APK。platform-tools/包含 adb、fastboot、sqlite3 这些调试工具日常连手机、抓日志基本靠它。cmdline-tools/是官方命令行工具替代了早期的 SDK Manager.exe里面提供sdkmanager和avdmanager。emulator/是模拟器本体system-images/则是模拟器用的系统镜像按API级别和ABI分目录。这个目录结构也解释了很多人遇到的一个问题“我明明装了Android SDK为什么报错找不到SDK”大概率是你只装了platform-tools没有装platforms和build-tools。一个完整可用的Android开发环境至少要有platform-tools 对应版本的platformsbuild-tools这三样缺一个都可能出幺蛾子。早年Android SDK还会带一个完整的tools/目录里面有ddms、monitor等工具现在已经全部迁移到cmdline-tools里了。如果你还在看那种老教程照着找tools目录、找SDK Manager.exe很可能会迷路这一点要提前有心理准备。1.2 先判断自己到底要装哪些版本装多少、装哪些版本取决于你平时做什么。如果你主要写原生Android应用建议在Android Studio里打开SDK Manager勾选当前项目需要的API版本和对应的build-tools再勾选Android SDK Platform-Tools和Android SDK Command-line Tools。如果你做Flutter/React Native这类跨平台开发Flutter命令会自动去读ANDROID_HOME但你需要先把command-line tools装好因为Flutter会调用sdkmanager去自动安装缺失的平台组件。如果你只想用ADB连手机抓日志理论上只装platform-tools就够但很多自动化测试框架依然依赖build-tools所以还是建议完整装一遍。版本选择上不建议盲目追新。新项目用API 34、35没问题但老项目可能锁定compileSdk 30或31。每个API级别对应一个platform目录我建议在SDK Manager里把常用的几个都装上比如34、35以及你公司老项目用的那个版本。磁盘吃紧时再单独清理不用的版本。拿我自己说吧手头维护一个三年前的老项目compileSdk 30targetSdk 30buildToolsVersion 30.0.3。如果我只装了最新的API 35和build-tools 35.0.0一编译就报“failed to find platform android-30”或者build-tools版本不匹配。所以建议先把你现有项目都打开看一眼记录下每个项目的compileSdk和buildToolsVersion再决定装什么别一上来就装一堆。1.3 API Level和Android版本号怎么对应API Level就是一个整数编号Android版本号是给人看的名字两者对应关系在官方版本列表中一目了然。比如Android 13对应API 33Android 14对应API 34Android 15对应API 35。你在SDK Manager里看到的是数字而不是“Android 13”这种名字所以找不到“android 13”是正常的那其实是android-33。明白这个对应关系以后配置依赖时思路就清晰了compileSdkVersion 34意味着需要安装platforms;android-34buildToolsVersion 34.0.0意味着需要安装build-tools;34.0.0。有时候你还得分清compileSdk和targetSdk前者决定编译时用哪个平台API后者决定应用在哪个Android版本上的兼容行为。默认情况下Gradle会使用已安装的最高版本build-tools但如果项目里显式指定了老版本本地没有就会报错。Android系统版本API LevelAndroid 1029Android 1130Android 1231Android 12L32Android 1333Android 1434Android 1535这张表不用背但心里要有数尤其是从老项目迁移过来的时候看到数字和品牌名对不上第一反应不是怀疑SDK坏了而是去查对应关系。2. 下载Android SDK的几种可靠渠道安卓SDK的下载渠道网上说法很多但真正靠谱的其实就那么几个。我按“省心程度”排个序Android Studio内置的SDK Manager最省心官网下载Command Line Tools最灵活国内镜像适合网络不好的人最后还有一种单独下载platform-tools的应急场景。下面一个个说。2.1 最省事的方式用Android Studio自带的SDK ManagerAndroid SDK的最优下载渠道其实不在浏览器里而在Android Studio内部。安装Android Studio后打开Preferences/Settings在 Appearance Behavior System Settings Android SDK就能看到SDK Manager界面。这里能看到所有可安装组件包括SDK Platforms、SDK Tools、SDK Update Sites勾选后点Apply就会自动下载并解压到指定目录。首次下载时需要注意两点第一SDK Location默认在用户目录下Windows是C:\Users\用户名\AppData\Local\Android\SdkmacOS是~/Library/Android/sdk。如果你不想C盘被塞满最好提前改成其他盘符比如D:\Android\Sdk。改晚了组件已经装过去再迁移就麻烦。第二在SDK Tools标签页里记得勾选最底部的“Show Package Details”这样能展开看到历史版本不会被迫只装最新版。这个细节很多人不知道后来碰到老项目要指定buildToolsVersion才发现当时没勾选只能回去补。如果你首次启动Android Studio在欢迎界面就能看到 Configure SDK Manager 入口很多人第一次没注意装完Studio就开始建项目一直等右下角那个SDK下载进度条其实那个进度条就是在自动下载SDK。如果网络不好进度条会一直卡着这时候同样可以去SDK Manager手动操作。Android Studio下载SDK的好处是按需勾选不需要手动配置JDK它自带的JBR可以跑通整个构建链路。所以如果你是新手我强烈建议从这条路开始别一上来就碰命令行。2.2 手动下载Command Line Tools适合偏命令行的玩家如果你不用Android Studio或者你的CI环境、Flutter、React Native需要纯命令行安装SDK那就要手动下载Android SDK Command Line Tools。入口在Android开发者官网的SDK工具下载页下载压缩包后解压。这里有个经典坑为了兼容旧目录结构下载后的文件夹通常是commandlinetools-win-xxxx里面是cmdline-tools目录你需要把它放到SDK根目录下并将这个cmdline-tools目录改名为latest。最终路径应该是SDK根目录/cmdline-tools/latest/bin/sdkmanager.bat。如果你直接把解压内容扔进去路径会变成cmdline-tools/cmdline-tools/bin/sdkmanager.bat后续运行sdkmanager就会报错找不到SDK。这个改名操作是官方文档里写的但很多人不看导致命令执行不了。我第一次也是这样折腾了半天才反应过来。放置好之后运行sdkmanager --version验证一下。Windows下可以先把sdkmanager.bat所在目录加入PATH或者运行时写完整路径。下载时注意区分平台Windows选windows包macOS选mac包Linux选linux包。如果你是在裸机环境手动安装还需要先把JDK装好因为sdkmanager本身是用Java写的没有JVM跑不起来。这一点放到后面常见问题部分详细说。2.3 国内镜像加速下载的注意事项官网下载在部分地区比较慢甚至断断续续我的经验是直接换国内镜像。Android SDK组件通常托管在dl.google.com上国内访问不稳定下载大文件很容易中断。比较好的办法是在SDK Manager里设置镜像源。在SDK Update Sites标签页点击Add名称随便填地址填写腾讯镜像https://mirrors.cloud.tencent.com/AndroidSDK/或者阿里镜像https://mirrors.aliyun.com/android/repository/repository2-1.xml。然后取消勾选官方源让镜像源生效。这样SDK Manager下载组件时会优先走镜像速度明显快不少。但镜像源有个问题同步官方仓库有时间差某些新版本组件不一定第一时间出现。如果列表里找不到最新API 35的platform切回官方源重试就好。如果你主要用命令行sdkmanager坦白说目前没有特别简单的官方镜像配置入口所以我建议命令行重度用户直接手动下载压缩包解压别在sdkmanager上死磕镜像。还有一条要提醒不要随便去第三方网站下载“完整SDK集成包”这些包经常捆绑广告、木马版本也混乱。官方渠道加上镜像已经足够满足99%的场景。2.4 单独下载platform-tools的应急场景有时候你会看到网上说“只需要下载platform-tools就能用adb”这句话半对半错。如果你只做接口调试、抓日志、重启设备那确实装platform-tools就够了但如果你想正常编译APK、跑模拟器或者开发Android应用依赖的组件远不止它一个。不过platform-tools确实可以单独下载因为官方提供了独立的压缩包解压后把里面的adb.exe、fastboot等文件放到SDK根目录下的platform-tools文件夹里就能用。这个操作适合应急比如你只需要用ADB连接手机又不想下载整个SDK但前提是你知道自己在干什么。我一般不建议手动复制因为后续SDK更新时你容易忘记自己改过什么版本混在一起反而难排查。能用sdkmanager或SDK Manager统一管理就尽量不要手动折腾。3. 一步步安装并配置环境变量SDK下载安装完成后如果不配环境变量很多命令行工具根本找不到它。尤其Flutter、React Native、Gradle、ADB这些都会通过ANDROID_HOME或PATH来定位SDK。这一章我按步骤来Windows和macOS/Linux分开讲你跟着自己系统操作就行。3.1 设置 ANDROID_HOME 与 PATHWindows上建议先去系统变量里新建一个ANDROID_HOME值填SDK根目录比如D:\Android\Sdk。然后在Path变量中追加三个路径%ANDROID_HOME%\platform-tools、%ANDROID_HOME%\cmdline-tools\latest\bin、%ANDROID_HOME%\emulator。注意有些教程会让你把整个tools目录加进去那是旧版SDK的做法现在已经不用了加了反而容易遇到奇怪的版本冲突。修改Path时一定不要覆盖原有变量点“编辑”再点“新建”每一行单独加一条确认时千万不要把原来的内容删了。macOS / Linux 上在~/.zshrc或~/.bashrc里加上下面的内容export ANDROID_HOME$HOME/Android/Sdk export PATH$PATH:$ANDROID_HOME/platform-tools export PATH$PATH:$ANDROID_HOME/cmdline-tools/latest/bin export PATH$PATH:$ANDROID_HOME/emulator加完执行source ~/.zshrc或source ~/.bashrc再输入adb --version验证。如果你用的是zsh别改错文件很多人改了.bash_profile而当前shell是zsh导致重启终端后环境变量不生效。设置完成后打开新的终端窗口SDK路径就自动识别了。这里有个细节某些版本sdkmanager命令没法直接使用可能是因为cmdline-tools/latest/bin没有加入PATH所以上面那一步加环境变量很关键。3.2 使用 sdkmanager 安装平台组件环境变量配好之后打开终端或命令行先运行sdkmanager --list查看可安装列表。这个命令会列出所有可用的 platform、build-tools、platform-tools 和其他工具输出很长建议后面跟管道过滤比如sdkmanager --list | grep platforms;android-35。常用安装命令如下# 安装平台工具 sdkmanager platform-tools platforms;android-35 # 安装指定版本的构建工具 sdkmanager build-tools;35.0.0 build-tools;34.0.0 # 安装模拟器和系统镜像 sdkmanager emulator system-images;android-35;google_apis;x86_64 # 接受所有已下载包的许可证 yes | sdkmanager --licenses为什么需要显式安装这些组件因为sdkmanager本质上是个极简安装器默认不会把所有东西都装上。Android Studio的SDK Manager会自动勾选常用组件但你一旦脱离Studio来维护SDK就得手动指定。另外安装系统镜像时要注意CPU架构Windows/macOS英特尔选x86_64Apple Silicon选arm64-v8a否则模拟器可能起不来。如果你不确定可以先跑sdkmanager --list | grep system-images看哪个镜像可用再根据宿主机架构选。3.3 验证安装结果确认环境真的能用安装完之后别急着高兴我一般按这个顺序验证先运行adb --version看adb能不能直接调用如果提示找不到命令说明PATH没配好。再运行sdkmanager --list_installed确认需要的组件已经装好最后打开你的项目看Android Studio里的SDK路径是否和ANDROID_HOME一致。如果Android Studio显示SDK Location未配置通常是你设置了环境变量但Studio没读取这时在项目结构里手动指定SDK路径即可。另外Android Studio新建项目时会提示选择SDK路径这个路径尽量和ANDROID_HOME保持一致不然后面Gradle会给出乱七八糟的报错。我自己见过好多同事ANDROID_HOME指向D盘Android Studio却默认C盘结果构建时来回横跳排查了许久才发现是路径不一致。顺便说一句如果命令行验证没问题但Android Studio里新建项目还是卡在下载SDK检查一下Gradle的SDK目录设置有时候Gradle会去读一个隐藏的local.properties文件导致和IDE显示的路径不一致。3.4 让Android Studio使用你配置好的SDK如果你不是通过Android Studio下载的SDK而是在命令行或镜像中手动安装的那要告诉Android Studio“SDK在哪”。打开Android Studio进入 File Project Structure SDK Location手动指定SDK路径。如果你建项目时IDE提示“SDK location not found”不用慌点开设置指过去就行。很多情况下IDE会读取ANDROID_HOME环境变量但如果你改过环境变量建议把IDE彻底重启一次别只关窗口还是从任务管理器里结束进程再打开否则可能还是会读到旧值。Android Studio新版本还会提示“SDK components missing”点链接进入SDK Manager补装即可。这块我见过很多人卡住其实就是因为Studio和实际SDK目录不一致。特别是你从命令行下载完SDK后直接打开原来项目IDE不会自动刷新需要手动指路径或重启。4. 常见问题与排查技巧实录这一章才是重点。SDK下载安装过程中的报错很多都有固定套路看懂错误信息就能少走弯路。4.1 SDK Manager超时或无法下载这个几乎每个人都遇到过。现象是SDK Manager下载进度条卡住或者一直报“Download interrupted”甚至直接提示无法访问服务器。解决思路是换源。我通常处理顺序是如果网络没问题但官方源慢把镜像地址加到SDK Update Sites并勾选镜像源如果配置过镜像但失效切回官方源看看是不是镜像没同步如果仍然失败删除SDK根目录下的.temp或.downloadIntermediates这类临时文件重新下载。临时文件损坏也会导致反复失败这一点容易被忽略。还有Windows上某些安全软件会拦截SDK Manager的下载进程如果突然无法下载可以先把防火墙或安全软件临时关掉试试。当然这里的前提是你网络本身通只是下载SDK组件慢。排障时可以先确认磁盘空间是否充足。SDK下载有时会下到一半失败表面看是网络实际是C盘满了。把SDK整个目录挪到其他盘或者清理一下临时目录问题就解决了。另外有些公司内网会屏蔽下载请求这种只能找管理员开白名单或者直接下载离线的zip包再解压到指定位置。4.2 sdkmanager运行报错找不到Java或JAVA_HOME新版Android SDK Command Line Tools运行sdkmanager需要JDK不能裸跑否则会看到类似“ERROR: JAVA_HOME is not set and no java command could be found in your PATH”的报错。我的建议是装一个JDK 17比较老的Android项目可能需要JDK 8或11然后配置好JAVA_HOME环境变量再把%JAVA_HOME%\bin加入Path。Windows下有些用户装完JDK后sdkmanager依然报错通常是因为JAVA_HOME指向了JRE而不是JDK检查一下路径是否正确。如果你实在不想单独装JDKAndroid Studio自带了一个JetBrains Runtime路径类似C:\Program Files\Android\Android Studio\jbr临时把JAVA_HOME指过去也能跑通sdkmanager。但这只是应急长期维护还是装一个独立JDK省心因为IDE自带的JBR可能跟命令行工具版本不完全兼容。还有就是新版sdkmanager要求JDK 17以上如果你还在用JDK 8可能会看到“Unsupported class file major version 65”之类的报错这时候该升级JDK了别死磕。4.3 SDK路径别碰中文和空格权限问题要留意Windows下最容易出问题的就是把SDK装到Program Files或带中文的路径里。Program Files自带空格部分老版本构建工具和第三方插件处理路径时不够稳健会报找不到文件或无法加载共享库。中文路径更麻烦Gradle和Java处理unicode路径时偶发编码问题症状非常诡异明明文件存在却报FileNotFoundException。推荐的路径是D:\Android\Sdk纯英文、无空格。Linux/macOS下如果SDK装在/opt等需要root权限的目录普通用户没有写权限SDK Manager无法创建临时文件和下载缓存。解决办法是执行sudo chown -R 用户名:用户组 /opt/android-sdk或者直接把SDK放到用户目录下更安全。共用CI机器时注意不要用root去装然后普通用户去跑权限不一致会带来一堆“Permission denied”的报错。我见过有人把SDK装到/root下面结果其他用户一编译就报权限错误改起来非常折腾。4.4 compileSdkVersion、targetSdkVersion和buildToolsVersion不匹配很多新手把SDK装好后新建项目依然报编译错误比如“failed to find Build Tools revision 34.0.0”或“Failed to find target with hash string android-34”。说白了就是项目声明的编译版本没有在本地SDK里找到对应组件。这类问题不是网络问题是版本匹配问题。碰到这种报错先看项目build.gradle里的compileSdk和buildToolsVersion是多少再去sdkmanager --list里确认本地有没有对应版本没有就补装。有几组常见组合可以参考compileSdkGradle/AGP建议最低版本需要安装的组件34AGP 8.1platforms;android-34, build-tools;34.0.035AGP 8.6platforms;android-35, build-tools;35.0.030AGP 7.0platforms;android-30, build-tools;30.0.3为什么总有这种问题因为Android每年发一个新版本老项目并没有跟着升级。如果你同时维护多个项目最简单的做法是把项目用到的所有platform和build-tools都装上别只装最新版。一个platform其实才几百MB相比下载时花费的时间多占点空间是值得的。另外如果你用Flutter它在构建时会自动安装缺少的Android SDK组件但前提是ANDROID_HOME配好了且网络能连上SDK仓库否则同样会卡在“Running Gradle task assembleDebug”步骤上。这个阶段别急着去改编译配置先看看SDK组件齐不齐。4.5 License未接受导致的安装失败用sdkmanager装组件时如果之前没接受过协议会提示需要运行sdkmanager --licenses如果忽略安装过程中会直接失败。Gradle编译时也可能报“You have not accepted the license agreements of the following SDK components”。解决办法很简单运行一次许可接受命令yes | sdkmanager --licenses在CI环境里强烈建议用yes |自动确认否则会卡在交互式输入上。Android Studio里则会在SDK Manager页面弹出许可协议点“Accept”后继续。这个小步骤看起来不起眼但确实会让整个安装流程中断尤其你第一次用命令行装系统镜像时忘了这一步后面创建模拟器会报license相关错误。我自己就遇到过一次装了模拟器但一直没法启动后来才发现是license没接受重新跑一遍sdkmanager --licenses后立刻好了。最后再分享一个我个人的习惯SDK装好之后我会在项目根目录放一个local.properties写上sdk.dirD:/Android/Sdk或sdk.dir/Users/xxx/Android/Sdk。虽然Studio也能自动识别但这个文件能让命令行构建和IDE都稳定指向同一个SDK尤其多端同步开发时省心很多。希望这篇能帮你把Android SDK下载安装这件事一次走通别再在环境配置上反复折磨自己了。