最近帮同事配一台全新的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.zip（Windows）
- commandlinetools-linux-11076708_latest.zip（Linux）
- commandlinetools-mac-11076708_latest.zip（macOS，Intel和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_64"system-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 --channel=3 # 卸载某个组件 ./sdkmanager --uninstall "platforms;android-34"channel参数可以这样理解：channel=0是稳定版，channel=1是测试版，channel=2是alpha版，channel=3是所有版本。平时不需要加这个参数，默认只显示稳定版，避免被一堆非正式版本干扰。
卸载命令也很实用。有些项目用的API版本是临时的，过段时间磁盘吃紧，就能用--uninstall把不用的平台清掉。
3.6 网络不稳定时的应对方案
官方下载服务器在一些网络环境下连接速度确实让人头疼。如果发现下载慢或者中断，我有几个实际用过的办法：
一是命令后面加上--verbose看详细日志，确认是否卡在某个具体文件上。
二是如果公司内网有SDK镜像仓库，可以试试配置镜像源。比如在SDK根目录创建repositories.cfg，在里面设置镜像地址，许多团队就是这么做的。
三是用代理参数：
./sdkmanager --proxy=http --proxy_host=你的代理地址 --proxy_port=你的代理端口 "platform-tools"把代理地址和端口换成你自己环境的实际值。这个参数只对当前命令生效，不会写进全局配置，不影响其他网络操作。
四是在极端情况下，直接用浏览器或者下载工具把需要的zip包下载下来，手动解压到对应目录里。不过这个方法要特别小心目录结构，手动放置时一旦位置放错，sdkmanager或者Gradle反而会因为目录混乱而报更多错。还是优先用sdkmanager本身。
4. 环境变量配置：让系统和项目找到SDK
cmdline-tools和组件都装好了，但如果不配置环境变量，很多开发工具还是找不到它们。这就像你把工具放进工具箱，但工具箱没放在手边，干活的时候还是得满屋子找。
4.1 ANDROID_HOME和ANDROID_SDK_ROOT
Android开发工具链中，环境变量是它们定位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目录加进PATH：
export 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.dir=D:\\Android\\Sdklocal.properties的优先级比环境变量高。也就是说，即使ANDROID_HOME没有配好，只要local.properties里写了正确路径，Gradle一样能找到SDK。所以如果你遇到“SDK location not found”的报错，优先检查这个文件是否存在、路径是否正确。
4.4 Gradle和Flutter如何自动发现SDK
Gradle的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中 |
| UnsupportedClassVersionError | JDK版本过老 | 升级到JDK 17 |
| SDK location not found | 环境变量或local.properties缺失、路径不对 | 设置ANDROID_HOME或sdk.dir |
| Failed to install package | 网络中断或服务器连接超时 | 重试或配置代理、镜像源 |
| Accept? (y/N) 重复弹出 | 之前没有接受过协议 | 执行yes | ./sdkmanager --licenses |
| adb: command not found | platform-tools未安装 | 安装platform-tools并确保在PATH中 |
| Warning: Could not create directory | SD卡目录权限不足 | 在用户目录下创建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、环境变量。每一步卡住了就回到这篇文章的对应章节对照排查。走完这一套，后面再配多少台机器，都是复制粘贴的事情。
