最近帮同事配一台全新的Linux构建机他问了个特别典型的问题能不能不装Android Studio就把Android SDK装好能而且不只是能对于自动化构建、Flutter开发或者只是想给项目准备一个干净可靠的编译环境来说用cmdline-tools直接装SDK反而比打开Android Studio的图形界面等它慢慢下载要快得多也更容易控制版本。这篇文章就把我自己的实操过程完整写下来。我会先从SDK的组成结构说起因为理解了结构你才知道自己到底“下载”的是什么然后走一遍cmdline-tools的下载、目录部署、sdkmanager常用命令、环境变量配置最后整理一份我在实际环境中踩过的坑和排查清单。无论你是在Windows、macOS还是Linux上做Android开发这套流程都通用。内容不复杂但细节很多顺序错了容易出事。1. 先搞清楚SDK并不是“一个安装包”而是一堆组件我第一次接触这个的时候也懵去官网下载SDK怎么页面上一堆文件名什么commandlinetools、platform-tools、platforms到底该下哪个这个困惑特别正常因为Android SDK从一开始就不是“一个安装包装完就结束”的东西它是一个按需分发的组件体系。1.1 组件到底有哪些各自管什么在命令行环境下你真正需要关心的组件大致是这么几类cmdline-tools本身就是一个工具包里面装着sdkmanager和avdmanager这两个核心命令行程序。sdkmanager负责下载和管理其他组件avdmanager负责创建和管理模拟器镜像。可以说cmdline-tools是所有命令行操作的地基。platform-tools包含adb、fastboot这类与设备交互的工具。adb的重要性不用多说连接真机调试、查看日志全得靠它。platforms;android-XX对应特定Android API级别的系统平台文件。比如platforms;android-35就是面向Android 15的平台库Gradle在编译时会用到它。build-tools;XX.Y.Z包含aapt2、d8、zipalign等编译期工具。Gradle构建APK时这些工具是真正干活的。ndk;XX.Y.Z如果你要写C/C原生代码才需要下载这个纯Java/Kotlin项目用不到。system-images;android-XX;google_apis;x86_64这组是模拟器系统镜像只有创建模拟器时才需要。emulator模拟器程序本体。我用一个生活化的类比cmdline-tools好像是应用商店的客户端platform-tools是手机数据线随时要用platforms和build-tools是装修用的建材按需采购NDK是特殊工种。你不需要一次全下载缺哪个装哪个。1.2 sdkmanager就是SDK的包管理器sdkmanager是一个基于Java的命令行工具它读取远端仓库的元数据列出所有可用的组件版本然后根据你指定的ID去下载解压。它的行为和npm、pip很像但有几个明显的优点每个组件都有明确的版本号可以精确锁定。组件之间互相独立不影响其他项目的SDK环境。下载是增量式的缺失哪个补哪个。支持非交互模式适合写进脚本和CI流水线。理解了这层结构你就会发现“下载SDK”这个说法其实不太准确。更准确的说法是先装好cmdline-tools再用sdkmanager按需挑选并下载其他SDK组件。接下来的安装过程就是围绕这个思路展开的。2. cmdline-tools下载与安装目录放不对后面全白搭cmdline-tools的安装本身不复杂复杂的是它的目录规范。官方有个隐藏的硬性要求很多人第一次都会在栽在这里。2.1 前置检查确认JDK环境sdkmanager是Java程序所以机器上必须先有JDK。早期的cmdline-tools用JDK 8就行现在官方推荐JDK 17。我在两台不同环境验证过JDK 8跑最新版cmdline-tools会直接报“UnsupportedClassVersionError”所以建议直接用JDK 17。检查方法很简单java -version如果没有安装或版本太老先去把JDK 17装好再回来继续。Linux发行版自带OpenJDK一般可以直接用Windows就下载官方JDK安装包macOS建议用Homebrew或者官方pkg都行。这步别跳过我见过好几个同事在这上面卡了半天。2.2 从官网下载cmdline-tools压缩包打开Android开发者官网的“Command line tools only”页面找到当前平台的下载链接。文件命名是有规律的commandlinetools-win-11076708_latest.zipWindowscommandlinetools-linux-11076708_latest.zipLinuxcommandlinetools-mac-11076708_latest.zipmacOSIntel和Apple Silicon通用那个数字串是内部版本号会随着官方更新变化不影响使用。下载后用unzip或者右键解压会得到一个名为cmdline-tools的文件夹里面包含bin目录、lib目录、NOTICE.txt等文件。2.3 最关键的硬性要求目录层级必须是cmdline-tools/latest这是整个安装过程中最容易踩坑的地方。官方要求cmdline-tools组件必须放在SDK根目录下的cmdline-tools/latest子目录中sdkmanager才会正常识别。也就是说正确的完整路径应该是你的SDK根目录/cmdline-tools/latest/ ├── bin/ │ ├── sdkmanager │ └── avdmanager ├── lib/ └── ...我第一次图省事把解压出来的cmdline-tools直接丢到了SDK根目录下结果运行sdkmanager就报错提示找不到。后来才知道sdkmanager会按照“当前工具目录的上级目录是SDK根目录”这个逻辑去定位目录结构。如果没有latest这一层它就无法正确推断SDK根目录。所以正确操作是先创建好SDK根目录比如~/Android/Sdk然后在里面创建cmdline-tools文件夹再把解压出来的cmdline-tools文件夹整体放进去后重命名为latest。你可以直接这样操作mkdir -p ~/Android/Sdk/cmdline-tools unzip commandlinetools-linux-11076708_latest.zip -d /tmp/cmdline-tools-tmp mv /tmp/cmdline-tools-tmp/cmdline-tools ~/Android/Sdk/cmdline-tools/latestWindows下类似解压之后把cmdline-tools目录剪切到目标位置并重命名为latest即可。完成后检查一下目录结构确认没问题再继续。2.4 验证工具是否可用进入cmdline-tools的bin目录运行sdkmanager查看版本cd ~/Android/Sdk/cmdline-tools/latest/bin ./sdkmanager --version如果能看到类似11076708这样的版本号输出说明cmdline-tools已经装好了。如果报找不到Java、或者提示某些类不存在基本可以确定是JDK版本不匹配回头再检查一遍JDK。3. 用sdkmanager下载并管理SDK组件工具本身装好只算完成了三分之一接下来的任务是用它真正把SDK组件下载到本地。这里我会把命令和可能碰到的交互都讲一遍。3.1 查看已安装和可用的组件列表先用这个命令快速确认当前sdkmanager能看到哪些远程组件./sdkmanager --list输出会分成两部分Installed packages已安装组件和Available Packages可用组件。Available Packages又按类别分组比如platforms;android-35、build-tools;35.0.0、platform-tools等。组件ID就是你下载时的唯一标识千万别记错格式分号前后都不能乱。只查看已安装的组件可以用./sdkmanager --list_installed这个命令在排查环境时会经常用到比如想知道当前平台到底装了几个API版本一条命令就够。3.2 下载platform-tools和平台组件我第一次配置时是这么装的./sdkmanager platform-tools platforms;android-35 build-tools;35.0.0这条命令会依次下载三个组件。sdkmanager会先显示License协议提示“Accept? (y/N)”如果一路yes就逐步确认。批量装多个组件时命令要分行写还是用一次空格分隔都可以。这里有个细节点platforms后面的数字必须对应你自己项目里compileSdk的版本。比如你的build.gradle里写的是compileSdk 35那就要装platforms;android-35。版本不一致虽然Gradle可能会自动触发下载但那种情况一般需要额外配置而且网络不好时很容易卡住。不如一开始就装齐。安装过程中sdkmanager会实时显示下载进度和解压状态。如果一切顺利你会看到Finished字样。下载完成后进入SDK根目录用tree或者ls看一下会看到platforms目录下多了android-35文件夹。3.3 批量安装模拟器相关组件如果你需要创建模拟器这些组件是必须的./sdkmanager emulator system-images;android-35;google_apis;x86_64system-images的命名规则是system-images;API级别;镜像类型;CPU架构。根据自己的需要选。下载量比较大几百MB到1GB都很常见网络条件不好的话会有点煎熬。装完后可以顺手装一个platform-tools保证adb能正常用。3.4 接受所有License协议这是容易被忽略的一步。很多构建工具在编译时不会自动替你做License确认Gradle或者Flutter检测到未接受的协议就会直接拒绝自动下载SDK组件。所以安装完组件之后建议顺手执行一次yes | ./sdkmanager --licensesyes命令会自动把所有许可协议都确认掉。这条命令执行完会在SDK根目录生成licenses目录里面保存着协议哈希文件。之后Gradle和Flutter在自动化构建时就可以直接利用SDK而不再需要人工点确认了。这个步骤对CI环境尤其重要脚本里少了这一步构建就有可能在安静的流水线里突然挂掉。3.5 指定版本、查看预览版、卸载组件sdkmanager还支持更多操作方式# 安装指定版本的build-tools ./sdkmanager build-tools;34.0.0 # 查看包括alpha/beta在内的预览版组件 ./sdkmanager --list --channel3 # 卸载某个组件 ./sdkmanager --uninstall platforms;android-34channel参数可以这样理解channel0是稳定版channel1是测试版channel2是alpha版channel3是所有版本。平时不需要加这个参数默认只显示稳定版避免被一堆非正式版本干扰。卸载命令也很实用。有些项目用的API版本是临时的过段时间磁盘吃紧就能用--uninstall把不用的平台清掉。3.6 网络不稳定时的应对方案官方下载服务器在一些网络环境下连接速度确实让人头疼。如果发现下载慢或者中断我有几个实际用过的办法一是命令后面加上--verbose看详细日志确认是否卡在某个具体文件上。二是如果公司内网有SDK镜像仓库可以试试配置镜像源。比如在SDK根目录创建repositories.cfg在里面设置镜像地址许多团队就是这么做的。三是用代理参数./sdkmanager --proxyhttp --proxy_host你的代理地址 --proxy_port你的代理端口 platform-tools把代理地址和端口换成你自己环境的实际值。这个参数只对当前命令生效不会写进全局配置不影响其他网络操作。四是在极端情况下直接用浏览器或者下载工具把需要的zip包下载下来手动解压到对应目录里。不过这个方法要特别小心目录结构手动放置时一旦位置放错sdkmanager或者Gradle反而会因为目录混乱而报更多错。还是优先用sdkmanager本身。4. 环境变量配置让系统和项目找到SDKcmdline-tools和组件都装好了但如果不配置环境变量很多开发工具还是找不到它们。这就像你把工具放进工具箱但工具箱没放在手边干活的时候还是得满屋子找。4.1 ANDROID_HOME和ANDROID_SDK_ROOTAndroid开发工具链中环境变量是它们定位SDK的重要依据。一般推荐设置export ANDROID_HOME~/Android/Sdk export ANDROID_SDK_ROOT~/Android/Sdk这两个变量其实指向同一个目录。ANDROID_HOME是现在的主流变量几乎所有构建工具都认它ANDROID_SDK_ROOT是旧版Android Tools使用的变量。为了兼容历史版本建议两个都设置值一模一样不冲突。设置之后记得让配置生效Linux和macOS要source一下profile文件Windows则在系统环境变量里添加即可。然后验证echo $ANDROID_HOME确认输出的是你的SDK路径没有多出空格或者尾部斜杠就行。4.2 PATH里加上platform-tools和cmdline-tools光有ANDROID_HOME还不够日常开发中你肯定希望直接在终端敲adb而不是每次敲全路径。所以需要把两个bin目录加进PATHexport PATH$PATH:$ANDROID_HOME/platform-tools export PATH$PATH:$ANDROID_HOME/cmdline-tools/latest/bin前者让你能直接用adb、fastboot后者让你能直接用sdkmanager、avdmanager。两个都加省心。之后新开一个终端窗口试试adb --version sdkmanager --version如果两个都有版本号输出说明环境已经配好了。4.3 local.properties与项目级SDK指向很多项目是通过local.properties来指定SDK位置的这个文件要放在项目根目录内容就一行sdk.dir/home/yourname/Android/SdkWindows下目录分隔符要写对要么用正斜杠要么转义反斜杠sdk.dirD:\\Android\\Sdklocal.properties的优先级比环境变量高。也就是说即使ANDROID_HOME没有配好只要local.properties里写了正确路径Gradle一样能找到SDK。所以如果你遇到“SDK location not found”的报错优先检查这个文件是否存在、路径是否正确。4.4 Gradle和Flutter如何自动发现SDKGradle的Android插件在查找SDK时顺序大致是这样的先看local.properties里的sdk.dir再看ANDROID_HOME环境变量最后尝试SDK根目录的默认位置。Flutter工具链的检测逻辑也类似但它还需要额外检查licenses是否已接受没有接受就会提示你运行flutter doctor --android-licenses去确认。有个实践心得在全新的构建环境中与其手动一个个装组件不如先把cmdline-tools和JDK装好配置好环境变量再让Gradle构建项目。Gradle会根据项目所需的compileSdk、build-tools版本自动触发SDK组件下载前提是licenses已经接受。这种“按需自动下载”的方式实际上比手动挨个安装还要省事。不过它也有个缺点首次构建时下载时间长而且如果网络中断不会自动续传还是得自己重试。所以我的习惯是关键项目手动预装好常用组件一般练习项目用Gradle自动补齐就够了。5. 高频问题与避坑实录这部分完全是从实操里总结出来的每一个都是我或者身边同事真实遇到过的错误。整理成清单方便你对照排查。5.1 常见报错速查报错信息主要原因解决方案找不到sdkmanager命令cmdline-tools没进PATH或者目录结构有误检查latest目录层级确认bin目录在PATH中UnsupportedClassVersionErrorJDK版本过老升级到JDK 17SDK location not found环境变量或local.properties缺失、路径不对设置ANDROID_HOME或sdk.dirFailed to install package网络中断或服务器连接超时重试或配置代理、镜像源Accept? (y/N) 重复弹出之前没有接受过协议执行yes | ./sdkmanager --licensesadb: command not foundplatform-tools未安装安装platform-tools并确保在PATH中Warning: Could not create directorySD卡目录权限不足在用户目录下创建SDK根目录避免使用系统级路径5.2 目录层级不对引发连环报错这是新手最容易踩的坑。有人把cmdline-tools解压后直接放在了SDK根目录然后运行任何命令都提示“The SDK directory is not writable”或者干脆报莫名的路径错误。排查方法很简单进入SDK根目录用ls看层级正确的是cmdtools在cmdline-tools/latest/bin里面。我前面特别强调latest这一层就是因为这个目录层级是sdkmanager推导根目录的依据。层级不对后面所有工具都会找不到组件。5.3 只装了cmdline-tools却没有platform-tools运行sdkmanager --list没问题但敲adb就提示command not found这基本就是没装platform-tools。sdkmanager和adb是两个不同的组件前者是安装工后者是干活工具。如果你需要连接真机调试platform-tools记得装。同样如果只装了platform-tools没装platforms编译时Gradle也会报错所以下载前先列一份“项目真实依赖清单”按清单安装效率最高。5.4 Windows下的权限和路径问题Windows环境有两个额外注意点。第一个是不要用管理员权限运行cmdline-tools因为管理员权限可能会让命令往C:\Program Files这样的系统目录写文件后续普通终端访问时就会因权限不足而失败。第二个是路径分隔符在PowerShell里执行sdkmanager platforms;android-35时分号是正常字符不需要额外转义但在某些自定义shell脚本里要格外注意字符串引用避免分号被当成分隔符。cmdline-tools本身对Windows支持没什么大问题但最好把SDK目录放在纯英文路径下避免中文路径或空格路径引发解析问题。5.5 下载到一半卡死或突然中断sdkmanager从设计上就不支持断点续传一旦网络中断只能从头再来。碰到这种情况我的建议是先把当前下载任务取消重新执行一次同样的命令。有时候第二次会跳过已完成的部分文件因为sdkmanager会检查已有文件的校验值。如果反复中断考虑用--verbose查看具体卡在哪个文件上然后针对性解决网络问题。批量下载改成逐个组件下载避免一个断点导致所有组件都回滚。如果网络实在不稳定可以考虑用前面提到的手动下载方案但一定要严格按照目录结构放置。这些方法不能百分百保证成功但至少能显著减少废掉的下载次数。5.6 licenses文件已接受但Gradle还是报授权未通过有一种情况比较隐蔽执行了yes | ./sdkmanager --licenses但Gradle构建时仍然提示“You have not accepted the license agreements of the following SDK components”。原因通常是licenses目录确实生成了但当前构建用的SDK目录和这个licenses目录不是同一个。比如ANDROID_HOME指向了A目录而local.properties里的sdk.dir指向了B目录两边组件不一致就会出现这个现象。排查思路先确认项目实际使用的SDK路径是哪个然后单独在那个目录下执行licenses接受操作。一句话每次环境变量或者SDK目录变动了都重新执行一遍licenses接受这是最保险的。最后分享一点我的使用习惯实际搞了这么多次命令行SDK安装我最深的体会是一定要把“安装SDK”这件事拆成“安装工具”和“安装组件”两个阶段来理解。工具阶段只做cmdline-tools部署组件阶段完全交给sdkmanager按需取用。这样环境出问题时排查范围小定位也快。另外再分享一个小技巧配置完SDK之后顺手在SDK根目录放一份简单的说明文件记录当前环境装了哪些组件、版本号、什么时候装的。别小看这一行记录半年后你再看这个环境就能快速判断哪些组件可以升级、哪些是特意锁定的旧版本。这个习惯帮我省了不知道多少排查时间。如果你是从零开始配环境按顺序走一遍就行JDK 17、cmdline-tools、latest目录、sdkmanager、platform-tools、平台组件、licenses、环境变量。每一步卡住了就回到这篇文章的对应章节对照排查。走完这一套后面再配多少台机器都是复制粘贴的事情。
